Hy3 APIガイド: 推論、ツール呼び出し、長文コンテキスト

Hy3 は、コーディング、推論、長文コンテキスト作業、エージェント向けのテキストのみの MoE モデルです。最初の統合では、ホストされた OpenAI 互換エンドポイントを使用し、通常の Chat Completions リクエストを送信して、実際に自動化するつもりの1つのワークフローを評価してください。ツールスキーマに従い、長い入力で重要となる制約を保持するようになるまでは、標準化しないでください。

以下のプロバイダー情報は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 の受け入れチェックを 3 つ返してください。"}
    ]
  }'

レスポンスは標準的な Chat Completions の形式を使用します。回答と請求フィールドは次のように解析します:

{
  "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] で終了する server-sent events として記載されています。

表内のプロバイダーの選択肢は意図的に限定されています。これらは価格順位ではなく、確認済みの公開アクセス経路です。

Tencentの2026年7月6日のリリース発表では、Hy3がopen-weightのMixture-of-Expertsモデルとして紹介されました。公式の価格発表とmodel cardにより、ホスト型評価の候補にはなりますが、APIページがあることは、それが本番ワークロードに適している証拠ではありません。

Hy3とは何か、そして何ではないか

Hy3は、トークンごとに21Bのアクティブパラメータを持つ295BパラメータのMoEモデルです。公式のHy3 model cardには、top-8 routingを備えた192 experts、80-layer backbone、1つのMTP layer、256K-tokenのcontext window、そしてApache 2.0 licenseが記載されています。

それらの数値は、推論、コーディング、長時間の会話、そしてツールを使うエージェント向けに設計されたテキストモデルを示しています。これらはHy3を画像モデルやOCRモデルにするものではありません。主要な入力がスキャンした請求書、スクリーンショット、製品写真、またはチャートであるワークフローでは、Hy3の前にまずVisionまたは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 はデフォルトの直接応答モードです。ソースがすでに構造化されており、答えの形が既知であり、応答が遅くなっても有用な推論が追加されない場合に適した基準です。たとえば、1つの文書化されたステータスを選び、1つの関数を呼び出すサポートワークフローは、まずこのモードでテストすべきです。厳密な JSON スキーマを追加し、長い推論連鎖があいまいな契約を修復してくれることを期待するのではなく、余分なフィールドを持つ応答は拒否してください。

エラーによって次のアクションが変わる場合は、低推論または高推論を使用します

モデルが複数のルールを整合させる必要がある場合や、コードに対して限定的な変更を行う必要がある場合は、low に移行してください。中間的な判断が弱いと高くつく再試行につながる作業、たとえば複数ファイルにまたがる失敗の診断、操作順序の選択、ツール呼び出し前の計算確認などには high を使ってください。

トレードオフは測定可能です。完了したタスク全体を比較してください。つまり、リクエストのレイテンシー、出力トークン数、ツール呼び出しの再試行回数、テスト失敗数、そしてレビュー担当者が回答を修正するのに費やす分数です。より思慮深く見えても、レビュー時間を減らさずにトークン数が2倍になるモードは、本番環境におけるより良い設定ではありません。

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 tool call の受け入れチェックを一覧にしてください。"}
    ],
    temperature=0.9,
    top_p=1.0,
    extra_body={
        "chat_template_kwargs": {"reasoning_effort": "low"}
    },
)

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

複雑なエージェントを評価する前に、この単純な呼び出しを動作させてください。これにより、認証、エンドポイント、テンプレート、またはモデル名の問題を、モデル品質の問題から切り分けられます。各試行ごとに、プロバイダー、利用可能であればモデルのリビジョン、推論モード、タイムスタンプ、入力トークン、出力トークン、および経過時間を記録してください。

実際のスキーマで構造化出力とツール呼び出しをテストする

ツール呼び出しは、「モデルがもっともらしいアクションを選択した」として評価されるべきではありません。明示的なスキーマを送信し、アプリケーションで返された引数を検証してください。これは OpenAI 形式のリクエスト断片です。これに依存する前に、プロバイダーに exact な tool パラメータのサポートを確認してください。

{
  "model": "tencent/Hy3",
  "messages": [
    {"role": "user", "content": "INC-1042 のステータスを確認してください。"}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_incident",
        "description": "ID によって 1 件のインシデントを検索します。",
        "parameters": {
          "type": "object",
          "properties": {"incident_id": {"type": "string"}},
          "required": ["incident_id"],
          "additionalProperties": false
        }
      }
    }
  ]
}

このリクエストでは、正しいツール選択とは、incident_id がちょうど INC-1042 である get_incident 呼び出しを意味します。あなたのコードは、下流システムに触れる前に、欠落したフィールド、不正な JSON 引数文字列、または予期しないツールを拒否する必要があります。5つの点を確認してください:

1. 選択されたツールは、そのタスクに対して使用が許可されています。

2. 必要な引数はすべて存在し、型も正しくなっています。

3. ID、日付、金額は、作り出されたものではなく、提供されたコンテキストに由来しています。

4. モデルは、欠けている必須値を推測するのではなく、それを要求します。

5. ツールエラーは、ループではなく、範囲が限定された修正またはエスカレーションの経路につながります。

有効な入力、曖昧なリクエスト、欠落したフィールド、そして意図的に失敗させるツール応答を含むように、十分な例を実行してください。正常系で信頼できる JSON が得られることは有用ですが、システムが引数を拒否したときにも信頼できる動作をすることこそが、エージェントがオペレーターの作業を増やさないために重要です。

制約保持のための長文コンテキストをテストし、見出しの長さは対象外

Hy3 の 256K コンテキストは、関連する事実がプロンプト形式の中で保持される場合にのみ有用です。代表的なリポジトリ、ポリシーバンドル、または顧客履歴スレッドからテストを作成してください。いくつかの具体的な制約を異なる場所に配置し、現実的な攪乱要素を追加し、それらの制約を引用または変換しなければならない回答を求めてください。

正確一致の検索、すべての指定された制約への遵守、根拠のない主張、そして総リクエストコストを採点してください。次に、本番の検索レイヤーを有効にした状態でもう一度繰り返してください。これにより、失敗がモデル、チャンク分割、検索ランキング、またはプロンプト組み立てコードのどれに属するかが明らかになります。1つの大きな貼り付けドキュメントを渡しただけでは、ガードレールを無効にする十分な証拠にはなりません。

移行を正当化できるワークロードをテストする

より優れたモデルの結果に明確なビジネス価値があるタスクを1つ選んでください。たとえば、複数ファイルにわたる失敗したテストの修復、長いポリシーからの義務の抽出、またはツールを使った複数ステップの内部操作の完了です。同じタイムアウトとレビューのルールの下で、現在の本番パスと Hy3 を比較してください。

完了タスク率、p50 と p95 のレイテンシ、入力トークンと出力トークン、ツールの再試行回数、レビュー担当者の修正時間を記録します。ここでは、混在するコミュニティからのフィードバックも役立ちます。Hy3 が優れているか期待外れかを、抽象的な主張だけで判断しないでください。実際に自動化するためにお金を払うタスクに基づいて判断してください。

ホスト型APIかセルフホスティングか？

モデルを評価している段階、トラフィックがまだ不確定な場合、またはチームが必要な GPU 容量をすでに運用していない場合は、まずホスト型 API を使用してください。これにより、上記のテストまでの道のりが短くなり、プロバイダーの可用性をアプリケーションロジックから分離できます。

具体的な制御、プライバシー、規模、またはレイテンシの理由があり、それを支えるインフラがある場合にのみ、自前でホストしてください。公式モデルカードでは、Hy3の提供には8基のH20-3e GPU、または同等の大容量メモリGPUを推奨しており、vLLMまたはSGLangのレシピが示されています。これはTencentの本番提供向け推奨であり、一般消費者向けノートPCが同等のデプロイを提供できるという主張ではありません。オープンウェイトを無料のインフラとみなす前に、GPU予約、アップグレード、監視、バッチ処理、オンコール運用のコストを、ホスト型サービスの請求額と比較して測定してください。

価格と提供状況は重みよりも速く変わることがあります

TencentはHy3 APIの価格を、7月6日に入力トークン100万件あたり1 RMB、出力トークン100万件あたり4 RMB、キャッシュされた入力トークン100万件あたり0.25 RMBとして掲載しました。それを日付付きの参照点として使用し、公開する前に実際のエンドポイント価格を確認してください。プロバイダーの無料枠、導入クレジット、または一時的な無料モデルのエイリアスは、実験用の利用可能性であって、恒久的な単価の約束ではありません。

簡単なコスト確認として、20Kの入力トークンと1Kの出力トークンを含む1日100件のリクエストでは、入力トークンは2M、出力トークンは0.1Mを使用します。Tencentが公開している参考価格では、これは1日あたり2.4元、30日で約72元です。もし2Mの入力トークンすべてがキャッシュ価格の対象になるなら、同じ計算で1日あたり0.9元になります。これはトークンのみの見積もりであり、プロバイダーの上乗せ料金、無料枠の制限、再試行、アプリケーションが追加するあらゆるコンテキストは含まれていません。

試用版の予算を見積もる際は、取得されたコンテキスト、システムプロンプト、ツール定義、再試行、そして選択した推論設定によって生成される出力を含めてください。主要な入力が視覚情報である場合、軽量なローカル展開が厳しい要件である場合、またはアプリケーションがツール引数と下流の副作用を検証できない場合は、Hy3を選択しないでください。

大きなコンテキストウィンドウ、設定可能な推論、オープンウェイトを必要とするテキスト中心のエージェントには、Hy3 は評価する価値のある妥当なモデルです。訂正にかかる時間を許容できる総コストで短縮できる場合にのみ、採用してください。

よくある質問

Hy3 はマルチモーダルですか?

いいえ。Hy3 はテキスト入力、テキスト出力のモデルです。タスクが画像、スキャン、またはスクリーンショットから始まる場合は、vision または OCR モデルを使用してください。

Hy3のコンテキストウィンドウとは何ですか？

Tencent のモデルカードには 256K トークンのコンテキストウィンドウが記載されています。長いコンテキスト上限があっても、関連する事実が取得される、またはそれに従って参照されることは保証されないため、代表的なソース資料で検証してください。

どの Hy3 推論モードから始めるべきですか？

no_think から始めて、境界が明確でレイテンシーに敏感な作業に使います。タスクの失敗コストと測定された改善が、追加のトークンと時間を正当化できる場合にのみ、low または high に移行してください。

Hy3 をセルフホストできますか？

はい。TencentはvLLMとSGLangのデプロイメントガイダンスを提供しており、サービングには大容量メモリGPUを8枚推奨しています。セルフホスティングは、オープンウェイトライセンスだけでなく、キャパシティと運用上の判断に基づいて行うべきです。

無料のHy3 APIは恒久的な料金プランですか？

いいえ。無料アクセスはプロバイダーごとに異なり、終了したり制限が変更されたりする場合があります。本番ワークフローに組み込む前に、現在のプロバイダーの利用規約と有料料金を確認してください。