Tencent의 Hy3가 Novita AI에서 모델 ID tencent/hy3로 제공됩니다. 이 모델은 OpenAI 호환 chat/completions 엔드포인트, 256K 컨텍스트 윈도우, 함수 호출, 구조화된 출력, 세 가지 추론 모드를 지원합니다. 이 빠른 시작 가이드는 개발자 설정 방법을 다룹니다: 클라이언트 구성, 첫 번째 요청 전송, 함수 호출 사용, 추론 활성화, 그리고 빌드 전에 알아야 할 속도 제한을 확인하세요.
이 빠른 시작 가이드를 사용해야 할 때
추가 코드를 작성하기 전에 Hy3에 대한 작동 가능한 요청이 필요할 때 이 가이드를 사용하세요. 실용적인 경로를 제공합니다: 모델 ID 선택, 인증, 하나의 테스트 요청 전송, 그런 다음 워크로드 필요에 따라 함수 호출 또는 추론으로 확장합니다.
Hy3의 아키텍처(총 295B, 활성 21B MoE)는 규모에 맞는 품질과 효율성의 균형을 맞추도록 설계되었습니다. 다음과 같은 상황에서 고려할 가치가 있습니다:
- 장문맥 문서 처리(256K 윈도우는 한 번의 호출에 약 200,000 단어에 해당).
- 대규모 활성 파라미터 예산의 이점을 누리는 다중 턴 대화.
- 도구 호출과 안정적인 인수 형식이 중요한 에이전틱 태스크.
- 청킹 없이 대규모 코드베이스를 다루는 코딩 지원.
이 가이드는 Novita AI를 통한 API 통합 경로만 다룹니다. 자체 호스팅, 파인튜닝, 또는 다른 추론 백엔드로의 포팅은 다루지 않습니다.
1단계: Novita API 키 받기
Novita AI 계정을 만들고 콘솔의 API 키 섹션으로 이동하세요. 키를 생성하고 환경 변수에 저장하세요. 클라이언트 측 코드, 프론트엔드 번들, 공개 저장소에 키를 넣지 마세요.
export NOVITA_API_KEY="your_api_key"
이미 OpenAI Python SDK나 다른 프로젝트에서 OpenAI 호환 클라이언트를 사용하고 있다면, 여기서의 설정도 동일합니다 — base URL과 모델 이름만 변경하면 됩니다.
2단계: 모델 ID 및 엔드포인트 확인
설정에 필요한 세 가지 값은 다음과 같습니다:
| 항목 | 값 |
|---|---|
| API 키 | 환경 변수로 저장된 Novita AI API 키 |
| OpenAI 호환 base URL | https://api.novita.ai/openai |
| 채팅 완료 엔드포인트 | POST https://api.novita.ai/openai/v1/chat/completions |
| 모델 ID | tencent/hy3 |
모든 API 호출에서 tencent/hy3를 사용하세요. 사용자 대상 UI 또는 문서에서는 표시 이름 "Hy3"를 사용하세요.
Novita AI 문서 인덱스에는 OpenAI 호환 base URL이 나열되어 있으며, 채팅 완료 API 참조에는 전체 요청 및 응답 형식이 문서화되어 있습니다.
3단계: 가격, 제한 및 모델 세부 정보 확인
Novita AI의 Hy3 모델 페이지에서 현재 값을 확인하세요:
| 필드 | 값 |
|---|---|
| 표시 이름 | Hy3 |
| API 모델 ID | tencent/hy3 |
| 모델 시리즈 | Hunyuan |
| 아키텍처 | MoE, 총 295B / 활성 21B |
| 엔드포인트 | chat/completions |
| 입력 모달리티 | 텍스트 |
| 출력 모달리티 | 텍스트 |
| 컨텍스트 윈도우 | 262,144 토큰 |
| 최대 출력 토큰 | 262,144 토큰 |
| 기능 | 서버리스, 함수 호출, 구조화된 출력, 추론 |
| 입력 가격 | $0 / M 토큰으로 표시됨 (모델 페이지에서 현재 요금 확인) |
| 출력 가격 | $0 / M 토큰으로 표시됨 (모델 페이지에서 현재 요금 확인) |
속도 제한은 계정 등급(T1–T5)에 따라 조정되며 분당 요청 수(RPM) 및 분당 토큰 수(TPM)로 측정됩니다. 현재 등급 임계값 및 제한은 Novita AI 속도 제한 문서에 나열되어 있습니다.
가격 및 속도 제한은 변경될 수 있습니다. 비용 추정을 확정하기 전에 Hy3 모델 페이지와 Novita AI 가격 페이지를 확인하세요.
4단계: 첫 번째 요청 보내기
간단한 텍스트 요청으로 시작하여 인증, 모델 라우팅, 응답 파싱을 확인하세요. 출력 품질이 아닌 연결성을 테스트하기 위해 프롬프트를 짧게 유지하세요.
cURL 예제
curl "https://api.novita.ai/openai/v1/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${NOVITA_API_KEY}" \
-d '{
"model": "tencent/hy3",
"messages": [
{
"role": "system",
"content": "You are a concise technical assistant."
},
{
"role": "user",
"content": "Describe the main trade-off between MoE and dense transformer architectures in three sentences."
}
],
"max_tokens": 256,
"temperature": 0.3
}'
성공적인 응답은 표준 채팅 완료 형식을 반환합니다: choices 배열, content가 있는 메시지, 모델 및 생성 메타데이터, 프롬프트, 완료, 총 토큰 수가 포함된 usage 객체입니다.
이 스모크 테스트를 사용하여 다음을 확인하세요:
- API 키가 유효하고 인증 헤더가 올바르게 포맷되었는지.
- 모델 ID
tencent/hy3가 404 또는 모델을 찾을 수 없음 오류 없이 허용되는지. - 클라이언트가
choices[0].message.content를 파싱할 수 있는지. - 토큰 사용량이 기록되어 첫 번째 요청부터 비용을 모니터링할 수 있는지.
Python 예제
OpenAI Python SDK는 base URL을 설정하면 Novita AI와 함께 작동합니다:
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.novita.ai/openai",
api_key=os.environ["NOVITA_API_KEY"],
)
response = client.chat.completions.create(
model="tencent/hy3",
messages=[
{"role": "system", "content": "You are a concise technical assistant."},
{
"role": "user",
"content": "Describe the main trade-off between MoE and dense transformer architectures in three sentences.",
},
],
max_tokens=256,
temperature=0.3,
)
print(response.choices[0].message.content)
print("Tokens used:", response.usage.total_tokens)
5단계: 응답 읽기
응답은 표준 OpenAI 채팅 완료 형식을 따릅니다:
{
"id": "chatcmpl-...",
"object": "chat.completion",
"created": 1751000000,
"model": "tencent/hy3",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "MoE models activate only a fraction of their total parameters..."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 52,
"completion_tokens": 80,
"total_tokens": 132
}
}
finish_reason 필드는 생성이 중단된 이유를 알려줍니다. stop은 모델이 자연스러운 종료 지점에 도달했음을 의미합니다. length는 max_tokens에 도달했음을 의미합니다. 짧은 프롬프트에서 length가 표시되면 max_tokens를 늘리거나 프롬프트를 줄이세요.
주요 파라미터
| 파라미터 | 타입 | 효과 |
|---|---|---|
model |
string | tencent/hy3이어야 함 |
messages |
array | 대화 기록. system, user, assistant 역할이 지원됩니다. |
max_tokens |
integer | 출력 토큰 상한. 명시적으로 설정하세요. 기본값은 클라이언트에 따라 다를 수 있습니다. |
temperature |
float (0–2) | 값이 낮을수록 결정론적인 출력이 생성됩니다. 코드 및 사실 기반 작업에는 0.1–0.3을 사용하고, 창의적 또는 다양한 출력에는 0.7–1.0을 사용하세요. |
top_p |
float (0–1) | 샘플링을 위한 temperature의 대안입니다. 둘을 동시에 설정하지 마세요. |
stream |
boolean | true로 설정하면 토큰을 스트림으로 수신합니다. 클라이언트에서 서버 전송 이벤트 처리가 필요합니다. |
tools |
array | 함수 호출을 위한 도구 정의입니다. 아래 함수 호출 섹션을 참조하세요. |
tool_choice |
string or object | 모델이 호출할 도구를 제어합니다. "auto"는 모델이 결정하도록 합니다. |
장문맥 워크로드의 경우 Hy3는 최대 262,144 입력 토큰을 지원합니다. 호출당 토큰 사용량을 예산에 맞추고, 대용량 문서나 긴 대화 기록을 처리하는 경우 누적 비용을 모니터링하세요.
함수 호출
Hy3는 tools 파라미터를 통해 함수 호출을 지원합니다. 모델이 일반 텍스트 대신 구조화된 인수를 반환하도록 하려면 이를 사용하세요 — 요청을 특정 작업으로 라우팅, 사용자 입력을 타입이 지정된 필드로 파싱, 또는 다단계 워크플로우 구동 등에 사용합니다.
import os
import json
from openai import OpenAI
client = OpenAI(
base_url="https://api.novita.ai/openai",
api_key=os.environ["NOVITA_API_KEY"],
)
tools = [
{
"type": "function",
"function": {
"name": "search_knowledge_base",
"description": "Search a product knowledge base for answers to customer queries.",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "The customer's question or topic to search for.",
},
"max_results": {
"type": "integer",
"description": "Maximum number of results to return. Default is 5.",
},
},
"required": ["query"],
},
},
}
]
response = client.chat.completions.create(
model="tencent/hy3",
messages=[
{"role": "system", "content": "You are a customer support assistant. Use the search tool to find relevant answers."},
{
"role": "user",
"content": "What is your return policy for electronics purchased in the last 30 days?",
},
],
tools=tools,
tool_choice="auto",
temperature=0.1,
)
message = response.choices[0].message
if message.tool_calls:
for call in message.tool_calls:
print(f"Tool: {call.function.name}")
args = json.loads(call.function.arguments)
print(f"Arguments: {args}")
else:
print(message.content)
모델이 도구 호출을 반환하면 애플리케이션이 함수를 실행한 다음 결과를 대화에 다시 보냅니다:
# After executing your search function, send the result back
tool_result = "Returns accepted within 30 days with original receipt. Electronics must be unopened."
follow_up = client.chat.completions.create(
model="tencent/hy3",
messages=[
{"role": "system", "content": "You are a customer support assistant."},
{"role": "user", "content": "What is your return policy for electronics purchased in the last 30 days?"},
message, # the assistant's tool call message
{
"role": "tool",
"tool_call_id": message.tool_calls[0].id,
"content": tool_result,
},
],
temperature=0.1,
)
print(follow_up.choices[0].message.content)
프로덕션 트래픽을 라우팅하기 전에 대표적인 쿼리로 도구 스키마를 테스트하세요. 함수 인수 추출의 품질은 각 파라미터와 예상 값을 얼마나 명확하게 설명하는지에 따라 달라집니다.
추론 모드
Hy3는 Novita AI 모델 페이지에서 지원되는 기능으로 추론을 나열합니다. 추론 가능 모델은 최종 답변을 생성하기 전에 문제를 생각하는 과정을 거치므로, 코드 디버깅, 다단계 수학, 장문서 분석, 계획 작업과 같은 복잡한 다단계 문제에서 출력 품질이 향상될 수 있습니다.
Novita AI 채팅 완료 API는 특정 모델에 대해 추론 관련 파라미터(separate_reasoning, enable_thinking)를 지원합니다. 이러한 파라미터가 tencent/hy3에서 허용되는지 여부와 정확한 요청 형식은 현재 Novita 문서에서 확인되지 않았습니다. Hy3로 프로덕션 워크플로우에 추론 동작을 구축하기 전에 테스트 호출을 실행하고 응답에 choices[0].message에 reasoning_content 필드가 포함되어 있는지 확인하세요.
확인된 파라미터 이름 및 지원되는 모델 ID에 대해서는 Novita AI 채팅 완료 API 참조와 추론 모델 가이드를 참조하세요.
장문맥 사용법
Hy3의 256K 컨텍스트 윈도우는 단일 호출로 대량의 텍스트를 유지해야 하는 작업에서 실용적인 이점을 제공합니다. 이 기능이 중요한 사용 사례:
- 문서 분석: 전체 계약서, 연구 논문 또는 사양을 컨텍스트로 보내고 청킹 없이 목표 질문을 합니다.
- 코드베이스 검토: 대용량 파일 또는 여러 관련 파일을 전달하고 아키텍처 관찰, 버그 패턴 또는 리팩토링 제안을 요청합니다.
- 긴 대화 기록: 많은 턴이 누적되는 에이전틱 워크플로우는 요약 또는 잘림이 필요하기 전에 더 오래 컨텍스트에 유지될 수 있습니다.
장문맥 호출의 경우 예상 출력 길이에 따라 max_tokens를 명시적으로 설정하세요. 200K 토큰의 입력을 보내고 출력 토큰 예산을 기본값으로 두면 컨텍스트 예산이 낭비되고 응답이 잘릴 수 있습니다.
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.novita.ai/openai",
api_key=os.environ["NOVITA_API_KEY"],
)
with open("large_document.txt") as f:
document_text = f.read()
response = client.chat.completions.create(
model="tencent/hy3",
messages=[
{
"role": "system",
"content": "You are a document analysis assistant. Provide specific, referenced answers.",
},
{
"role": "user",
"content": f"Here is the document:\n\n{document_text}\n\nSummarize the key obligations and deadlines in this document.",
},
],
max_tokens=1024,
temperature=0.2,
)
print(response.choices[0].message.content)
응답에서 usage.prompt_tokens를 모니터링하여 입력이 소비하는 토큰 양을 추적하세요. 동일한 시스템 프롬프트나 문서 프리앰블을 반복적으로 보내는 워크로드의 경우, 속도 제한 및 비용 계획은 문서 문자 수가 아닌 실제 프롬프트 토큰 수에 따라 달라집니다.
문제 해결
401 Unauthorized: API 키가 없거나, 만료되었거나, 잘못 포맷되었습니다. Authorization 헤더가 Bearer <your_key> 형식이고 공백과 추가 문자가 없는지 확인하세요.
404 또는 모델을 찾을 수 없음: 모델 ID가 잘못되었습니다. 정확한 문자열 tencent/hy3가 Novita AI 모델 페이지에 표시된 ID와 일치하는지 확인하세요. 모델 ID는 대소문자를 구분합니다.
429 속도 제한: 등급에 대한 요청 또는 토큰 분당 한도를 초과했습니다. 지수 백오프를 사용한 재시도 로직을 추가하거나, 워크로드가 지속적으로 필요하다면 더 높은 등급을 요청하세요.
finish_reason: length: 응답이 max_tokens에 도달하여 잘렸습니다. 더 긴 출력이 필요하면 max_tokens 값을 높이세요. 단, 출력 토큰은 비용과 지연 시간에 영향을 미칩니다.
첫 번째 응답이 느림: 대규모 모델 배포는 첫 번째 요청에서 짧은 콜드 스타트 지연 시간이 있을 수 있습니다. 동일한 엔드포인트에 대한 후속 요청은 일반적으로 더 빠릅니다. 지연 시간이 엄격한 요구 사항이라면 프로덕션 출시 전에 목표 동시성 수준에서 처리량을 테스트하세요.
도구 호출이 예상치 못한 인수 반환: 도구 스키마를 수정하세요. 각 파라미터에 더 구체적인 설명을 추가하고, 설명 필드에 예제 값을 포함하며, 필수 필드를 명시적으로 나열하세요. 먼저 단순화된 스키마로 테스트한 다음 복잡성을 추가하세요.
FAQ
Hy3가 Novita AI에서 사용 가능한가요?
네. Novita AI는 Hy3를 API 모델 ID tencent/hy3의 서버리스 LLM으로 나열합니다.
올바른 모델 ID는 무엇인가요?
모든 API 호출에서 tencent/hy3를 사용하세요. 사용자 대상 텍스트에서는 "Hy3"를 사용하세요.
어떤 엔드포인트를 사용해야 하나요?
OpenAI 호환 채팅 완료 엔드포인트를 사용하세요: POST https://api.novita.ai/openai/v1/chat/completions. OpenAI SDK를 사용할 때 base URL을 https://api.novita.ai/openai로 설정하세요.
컨텍스트 윈도우는 얼마나 큰가요?
Hy3는 Novita AI 모델 페이지에 나열된 대로 262,144 토큰 컨텍스트 윈도우와 최대 262,144 출력 토큰을 지원합니다.
Hy3가 함수 호출을 지원하나요?
네. Hy3는 채팅 완료 요청의 tools 파라미터를 통해 함수 호출을 지원합니다. Novita는 함수 호출 및 구조화된 출력을 지원되는 기능으로 나열합니다.
Hy3가 추론을 지원하나요?
추론은 Novita AI 모델 페이지에서 기능으로 나열되어 있습니다. tencent/hy3에서 추론을 활성화하기 위한 특정 요청 파라미터는 현재 Novita 문서에서 확인되지 않았습니다. 프로덕션에 추론 동작을 구축하기 전에 Novita AI 채팅 완료 API 참조를 확인하고 테스트 호출을 실행하여 파라미터 형식을 검증하세요.
Hy3는 어떤 입력을 받나요?
Hy3는 텍스트 입력만 받습니다. Novita AI 모델 페이지에 이미지 또는 비디오 모달리티가 나열되어 있지 않습니다.
Hy3의 아키텍처는 무엇인가요?
Hy3는 총 295B 파라미터와 순방향 패스당 21B 활성 파라미터를 가진 MoE(Mixture of Experts) 아키텍처를 사용합니다. 이를 통해 유사한 품질의 밀집 모델보다 낮은 계산 비용으로 대규모 컨텍스트 요청을 처리할 수 있습니다.
더 높은 속도 제한을 받으려면 어떻게 해야 하나요?
속도 제한은 계정 등급에 따라 조정됩니다. 현재 등급 임계값 및 제한은 Novita AI 속도 제한 문서에 나열되어 있습니다. 업그레이드 옵션에 대해서는 Novita AI 지원팀에 문의하세요.
