Hy3 API 가이드: 추론, 도구 호출, 그리고 긴 컨텍스트

Hy3는 코딩, 추론, 긴 컨텍스트 작업, 그리고 에이전트를 위한 텍스트 전용 MoE 모델입니다. 첫 번째 통합에서는 호스팅된 OpenAI 호환 엔드포인트를 사용하고, 일반 Chat Completions 요청을 보내며, 실제로 자동화할 단 하나의 워크플로를 평가하세요. 귀하의 툴 스키마를 따르고 긴 입력에서 중요한 제약을 유지하기 전까지는 이를 표준으로 삼지 마세요.

아래의 제공업체 세부 정보는 2026년 7월 14일에 확인되었습니다. DeepInfra 문서에서는 해당 모델을 OpenAI 호환 Chat Completions 엔드포인트에서 tencent/Hy3로 문서화합니다. SiliconFlow도 Hy3를 나열합니다 동일한 모델 ID 아래에서. 제공업체의 가격, 제한, 별칭은 변경될 수 있으므로, 배포하기 전에 현재 제공업체 페이지를 확인하세요.

호스팅된 Hy3 API 호출로 시작하기

DeepInfra는 호스팅된 Hy3 엔드포인트에 대한 이 최소 요청을 제공합니다. 토큰을 자신의 제공자 토큰으로 바꾸고, 브라우저 코드나 클라이언트 앱에 넣지 마세요.

curl "https://api.deepinfra.com/v1/openai/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPINFRA_TOKEN" \
  -d '{
    "model": "tencent/Hy3",
    "messages": [
      {"role": "user", "content": "API 수락 검사를 세 가지 반환하세요."}
    ]
  }'

응답은 표준 Chat Completions 형식을 사용합니다. 다음과 같이 answer 및 billing 필드를 파싱하세요:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "tencent/Hy3",
  "choices": [{
    "message": {"role": "assistant", "content": "..."},
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}

답변은 choices[0].message.content를, 토큰 사용량은 usage를 읽으세요. "stream": true는 비스트리밍 요청이 작동한 후에만 추가하세요. DeepInfra는 스트리밍을 [DONE]으로 끝나는 서버 전송 이벤트로 문서화합니다.

표의 제공업체 선택지는 의도적으로 제한되어 있습니다. 이는 가격 순위가 아니라 검증된 공개 접근 경로입니다.

Tencent의 2026년 7월 6일 출시 발표는 Hy3를 오픈 가중치 Mixture-of-Experts 모델로 소개했습니다. 공식 가격 발표와 모델 카드에 따르면 호스팅 평가의 후보가 될 수 있지만, API 페이지가 있다고 해서 그것이 프로덕션 워크로드에 적합하다는 증거는 아닙니다.

Hy3가 무엇이고, 무엇이 아닌가

Hy3는 토큰당 21B의 활성 파라미터를 가진 295B 파라미터 MoE 모델입니다. 공식 Hy3 모델 카드에는 top-8 라우팅을 사용하는 192개의 expert, 80층 backbone, 1개의 MTP layer, 256K-token context window, 그리고 Apache 2.0 라이선스가 명시되어 있습니다.

그 수치들은 추론, 코딩, 장시간 대화, 그리고 도구를 사용하는 에이전트를 위해 설계된 텍스트 모델을 설명합니다. 그것들은 Hy3를 이미지나 OCR 모델로 만들지 않습니다. 핵심 입력이 스캔한 송장, 스크린샷, 제품 사진 또는 차트인 워크플로는 Hy3보다 먼저 비전 또는 OCR 모델이 필요합니다. 그 경계를 명확히 유지하면 흔한 아키텍처 실수를 피할 수 있습니다. 즉, 유능한 텍스트 모델에 애초에 받지 못한 정보를 복원하라고 요구하는 것입니다.

Tencent은 Hy3를 코딩, 사무 작업, 재무 모델링, 프론트엔드 작업, 게임 개발용으로 포지셔닝합니다. 이를 보편적인 순위가 아니라 후보 워크로드로 간주하세요.

한계와 함께 벤치마크 주장 읽기

Tencent의 출시 발표에서는 270명의 전문가가 업무를 수행한 블라인드 평가 결과를 보고하며, Hy3는 4점 만점에 2.67점, GLM-5.1은 4점 만점에 2.51점을 기록했습니다. 같은 출처에 따르면 Hy3의 SWE-Bench Verified 정확도는 CodeBuddy, Cline, KiloCode 스캐폴드 전반에서 4퍼센트포인트 미만으로 변동했습니다. 이는 Tencent가 보고한 결과이며, Hy3가 사용자의 환경에서 특정 경쟁 모델을 능가한다는 독립적인 보증은 아닙니다.

Artificial Analysis는 모델 수준 측정의 또 다른 기준점입니다. 벤치마크 수치는 애플리케이션 수준의 수용 기준을 대체하는 것이 아니라, 모델 선택을 위한 입력값으로 읽어야 합니다.

실패 비용에 따라 추론 모드를 선택하세요

Hy3는 공식 서빙 예제에서 no_think, low, 그리고 high 추론 노력 수준을 제공합니다. 선택은 추론 모델을 사용하는 것의 명성보다는 잘못된 답변의 비용을 따라야 합니다.

제한된 작업에는 no-think를 유지하세요

no_think는 기본 직접 응답 모드입니다. 원본이 이미 구조화되어 있고, 답변의 형식이 이미 정해져 있으며, 더 느린 응답이 유용한 추론을 추가하지 못할 때 적절한 기준선입니다. 예를 들어, 하나의 문서화된 상태를 선택하고 하나의 함수를 호출하는 지원 워크플로는 먼저 이 모드에서 테스트해야 합니다. 엄격한 JSON 스키마를 추가하고, 더 긴 추론 과정을 통해 모호한 계약을 고칠 수 있을 것이라 기대하기보다 추가 필드가 있는 응답은 거부하세요.

오류가 다음 동작을 변경할 때 낮은 또는 높은 추론을 사용하세요

모델이 여러 규칙을 조정해야 하거나 코드에 제한된 변경을 해야 할 때는 low로 설정하세요. 파일 전반의 실패를 진단하거나, 작업 순서를 정하거나, 도구 호출 전에 계산을 확인하는 등 약한 중간 판단이 값비싼 재시도를 초래하는 작업에는 high를 사용하세요.

트레이드오프는 측정 가능합니다. 전체 완료된 작업을 비교해 보세요: 요청 지연 시간, 출력 토큰 수, 도구 호출 재시도, 테스트 실패, 그리고 검토자가 답변을 수정하는 데 쓰는 분 단위 시간. 더 사려 깊어 보이지만 토큰을 두 배로 늘리고도 검토 시간을 줄이지 못하는 모드는 더 나은 프로덕션 설정이 아닙니다.

Hy3를 도입하기 전에 4단계 API 시험을 실행하세요

이 시험은 일반적인 모델 판정이 아니라 귀하의 시스템에 대한 증거를 만듭니다. 실제이지만 민감하지 않은 작업을 사용하세요. 모델을 실행하기 전에 프롬프트, 스키마, 통과 기준을 고정하여 답변을 읽은 후 목표를 바꾸지 않도록 하세요.

최소한의 자체 호스팅 호출로 요청 경로를 증명하세요

다음 예시는 Hy3의 공식 자체 호스팅 OpenAI 호환 서빙 패턴을 따릅니다. 이는 로컬 vLLM 호환 엔드포인트와 해당 서버에서 구성한 모델 이름을 사용합니다. 호스팅된 모델 ID는 공급자별로 다르므로, 검증된 호스팅 ID는 위의 공급자 표를 사용하세요.

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8000/v1",
    api_key="EMPTY",
)

response = client.chat.completions.create(
    model="hy3",
    messages=[
        {"role": "user", "content": "JSON 도구 호출에 대한 수락 기준을 나열하세요."}
    ],
    temperature=0.9,
    top_p=1.0,
    extra_body={
        "chat_template_kwargs": {"reasoning_effort": "low"}
    },
)

print(response.choices[0].message.content)

복잡한 에이전트를 평가하기 전에 이 간단한 호출이 작동하도록 하세요. 이렇게 하면 인증, 엔드포인트, 템플릿 또는 모델 이름 문제를 모델 품질 문제와 분리할 수 있습니다. 모든 시도에 대해 제공자, 가능한 경우 모델 버전, reasoning mode, 타임스탬프, 입력 토큰, 출력 토큰, 그리고 경과 시간을 기록하세요.

실제 스키마로 구조화된 출력과 도구 호출을 테스트하세요

도구 호출은 "모델이 그럴듯한 작업을 선택했다"는 식으로 평가되어서는 안 됩니다. 명시적인 스키마를 전송하고 애플리케이션에서 반환된 인수를 검증하세요. 이는 OpenAI 스타일의 요청 조각입니다. 이에 의존하기 전에 제공업체와 정확한 도구 매개변수 지원을 확인하세요.

{
  "model": "tencent/Hy3",
  "messages": [
    {"role": "user", "content": "사건 INC-1042의 상태를 확인하세요."}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_incident",
        "description": "식별자를 기준으로 하나의 사건을 조회합니다.",
        "parameters": {
          "type": "object",
          "properties": {"incident_id": {"type": "string"}},
          "required": ["incident_id"],
          "additionalProperties": false
        }
      }
    }
  ]
}

이 요청에서 올바른 도구 결정은 incident_id가 정확히 INC-1042인 get_incident 호출을 의미합니다. 코드는 다운스트림 시스템에 닿기 전에 누락된 필드, 잘못된 형식의 JSON 인수 문자열, 또는 예상하지 못한 도구를 거부해야 합니다. 다섯 가지를 검사하세요:

1. 선택된 도구는 해당 작업에 허용됩니다.

2. 모든 필수 인수가 존재하며 올바른 형식으로 입력되었습니다.

3. ID, 날짜, 금액은 만들어내는 것이 아니라 제공된 컨텍스트에서 가져옵니다.

4. 모델은 누락된 필수 값을 추측하지 않고 요청합니다.

5. 도구 오류가 발생하면 무한 루프가 아니라 제한된 수정 또는 에스컬레이션 경로로 이어집니다.

유효한 입력, 모호한 요청, 누락된 필드, 그리고 의도적으로 실패하는 하나의 tool 응답을 포함할 만큼 충분한 예제를 실행하세요. 정상 경로에서의 신뢰할 수 있는 JSON은 유용하지만, 시스템이 인수를 거부할 때의 신뢰할 수 있는 동작이야말로 에이전트가 운영자에게 추가 작업을 만들지 않게 해줍니다.

제목 길이가 아니라 제약 유지용으로 긴 컨텍스트를 테스트

Hy3의 256K 컨텍스트는 관련 사실이 프롬프트 형식 안에서 유지될 때만 가치가 있습니다. 대표적인 저장소, 정책 번들 또는 고객 기록 스레드를 바탕으로 테스트를 만드세요. 서로 다른 위치에 몇 가지 구체적인 제약을 넣고, 현실적인 방해 요소를 추가한 뒤, 그 제약을 인용하거나 변환해야만 하는 답변을 요청하세요.

정확한 검색, 모든 명시된 제약 조건의 준수, 지원되지 않는 주장, 그리고 총 요청 비용을 점수화하십시오. 그런 다음 프로덕션 검색 계층을 활성화한 상태로 다시 반복하십시오. 이를 통해 실패가 모델, 청킹, 검색 순위, 또는 프롬프트 조립 코드 중 어디에 속하는지 드러납니다. 하나의 큰 붙여넣은 문서를 통과시키는 것만으로는 가드레일을 끄기 위한 충분한 근거가 되지 않습니다.

마이그레이션을 정당화할 수 있는 워크로드를 테스트하세요

더 나은 모델 결과가 명확한 비즈니스 가치를 가지는 하나의 작업을 선택하세요: 여러 파일에 걸친 실패한 테스트를 수정하기, 긴 정책에서 의무 사항을 추출하기, 또는 도구를 사용해 여러 단계를 거치는 내부 작업을 완료하기. 동일한 타임아웃과 검토 규칙하에서 현재의 프로덕션 경로와 Hy3를 비교하세요.

완료 작업 비율, p50 및 p95 지연 시간, 입력 및 출력 토큰, 도구 재시도 횟수, 그리고 검토자 수정 시간을 기록하세요. 또한 이 지점에서 혼합된 커뮤니티 피드백이 유용해집니다. Hy3가 추상적으로 뛰어나거나 실망스럽다는 주장만으로 판단하지 마세요. 실제로 자동화하는 데 비용을 지불할 작업을 기준으로 판단하세요.

호스팅된 API 또는 자체 호스팅?

모델을 평가 중이거나, 트래픽이 아직 불확실하거나, 팀에 이미 필요한 GPU 용량을 운영하고 있지 않다면 먼저 hosted API를 사용하세요. 이는 위의 테스트로 가는 경로를 단축하고 provider 가용성을 애플리케이션 로직과 분리해 줍니다.

구체적인 제어, 프라이버시, 용량 또는 지연 시간상의 이유가 있고 이를 지원할 인프라가 있을 때만 자체 호스팅하세요. 공식 모델 카드는 vLLM 또는 SGLang 레시피를 사용해 Hy3를 서빙하기 위해 8개의 H20-3e GPU 또는 기타 대용량 메모리 GPU를 권장합니다. 이는 Tencent의 프로덕션 서빙 권장 사항이지, 소비자용 노트북이 동등한 배포를 제공한다는 의미는 아닙니다. 오픈 가중치를 무료 인프라로 간주하기 전에 GPU 예약, 업그레이드, 모니터링, 배치 처리, 온콜 책임의 비용을 호스팅 요금과 비교해 측정하세요.

가격과 재고는 저울보다 더 빨리 변할 수 있습니다

Tencent은 Hy3 API 가격을 공개했습니다. 7월 6일 기준으로 입력 토큰 100만 개당 1 RMB, 출력 토큰 100만 개당 4 RMB, 캐시된 입력 토큰 100만 개당 0.25 RMB입니다. 이를 날짜가 명시된 참고 기준으로 삼은 뒤, 실제 엔드포인트 가격을 배송 전에 확인하세요. 제공업체의 무료 티어, 초기 크레딧, 또는 임시 무료 모델 별칭은 실험용 가용성일 뿐, 영구적인 단가 약속이 아닙니다.

간단한 비용 확인을 위해, 입력 토큰 20K와 출력 토큰 1K를 포함하는 일일 요청 100건은 입력 토큰 2M과 출력 토큰 0.1M을 사용합니다. Tencent의 공개 기준 가격에 따르면 이는 하루 2.4 RMB, 즉 30일 기준 약 72 RMB입니다. 모든 2M 입력 토큰이 캐시 가격 적용 대상이라면, 같은 계산으로 하루 0.9 RMB입니다. 이는 토큰만 기준으로 한 추정치이며, 제공업체 마진, 무료 요금제 제한, 재시도, 그리고 애플리케이션이 추가하는 모든 컨텍스트는 제외됩니다.

시험 사용 예산을 책정할 때는 검색된 컨텍스트, 시스템 프롬프트, 도구 정의, 재시도, 그리고 선택한 reasoning 설정이 생성한 출력을 포함하세요. 핵심 입력이 시각 정보인 경우, 가벼운 로컬 배포가 반드시 필요하거나 애플리케이션이 도구 인자와 후속 부작용을 검증할 수 없는 경우에는 Hy3를 선택하지 마세요.

대용량 컨텍스트 창, 구성 가능한 추론, 그리고 오픈 웨이트가 필요한 텍스트 중심 에이전트라면, Hy3는 평가해볼 만한 합리적인 모델입니다. 수정을 위한 시간을 허용 가능한 총 비용으로 줄여줄 때만 유지하세요.

자주 묻는 질문

Hy3는 멀티모달인가요?

아니요. Hy3는 텍스트 입력, 텍스트 출력 모델입니다. 작업이 이미지, 스캔, 또는 스크린샷으로 시작되면 vision 또는 OCR 모델을 사용하세요.

Hy3 컨텍스트 윈도우란 무엇인가요?

Tencent의 모델 카드에는 256K 토큰 컨텍스트 윈도우가 나와 있습니다. 긴 컨텍스트 한도가 관련 사실이 검색되거나 따를 것임을 보장하지 않으므로, 대표적인 소스 자료로 이를 검증하세요.

어떤 Hy3 추론 모드로 시작해야 하나요?

제한적이고 지연 시간에 민감한 작업은 no_think로 시작하세요. 작업의 실패 비용과 측정된 개선이 추가 토큰과 시간을 정당화할 때만 low 또는 high로 이동하세요.

Hy3를 자체 호스팅할 수 있나요?

예. Tencent는 vLLM 및 SGLang 배포 가이드를 제공하며, 서빙을 위해 대용량 메모리 GPU 8개를 권장합니다. 자체 호스팅은 오픈 가중치 라이선스만이 아니라 용량과 운영에 대한 의사결정을 따라야 합니다.

무료 Hy3 API는 영구적인 요금제인가요?

아니요. 무료 액세스는 제공자별로 다르며, 종료되거나 제한이 변경될 수 있습니다. 운영 워크플로우를 확정하기 전에 현재 제공자 약관과 유료 요금을 확인하세요.