Hy3 API 指南：推理、工具呼叫與長上下文

Hy3 是一個僅文字的 MoE 模型，適用於程式撰寫、推理、長上下文工作與 agents。作為首次整合，請使用託管的 OpenAI 相容端點，送出一般的 Chat Completions 請求，並評估你實際會自動化的那一個工作流程。在它遵循你的工具 schema 並保留你長輸入中重要的限制之前，請不要將其標準化採用。

以下提供的供應商詳細資訊已於 2026 年 7 月 14 日核對。DeepInfra 文件將該模型在其相容 OpenAI 的 Chat Completions 端點上標示為 tencent/Hy3。SiliconFlow 也將 Hy3 列在相同的模型 ID 下。供應商的價格、限制與別名可能會變動，因此在正式上線前請先確認即時的供應商頁面。

從託管的 Hy3 API 呼叫開始

DeepInfra 發布了這個針對其託管 Hy3 端點的最小請求。請將 token 替換為您自己的供應商 token；不要將它放在瀏覽器程式碼或用戶端應用程式中。

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 格式。請像這樣解析答案和計費欄位：

{
  "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 進行 token 計算。只有在非串流請求可正常運作後，才加入 "stream": true；DeepInfra 將串流說明為以 [DONE] 結尾的伺服器推送事件。

表格中的供應商選項是刻意縮小範圍的。它們是已驗證的公開存取路徑，而不是價格排名。

供應商	已驗證的存取詳細資訊	正式上線前需確認的事項
DeepInfra	`https://api.deepinfra.com/v1/openai/chat/completions`；模型 `tencent/Hy3`；已提供標準與串流範例文件	目前價格、帳戶限制、工具支援，以及資料條款
SiliconFlow	OpenAI 相容 API；模型 `tencent/Hy3`	目前端點、價格、速率限制，以及 API 金鑰範圍
OpenRouter	7 月 14 日，其頁面列出 `tencent/hy3:free`，並標示免費版本將於 7 月 21 日結束	該別名是否仍可使用、其限制，以及路由的供應商

騰訊於 2026 年 7 月 6 日發布的公告將 Hy3 介紹為一個開放權重的 Mixture-of-Experts 模型。其官方定價公告與 model card 使其成為託管式評估的候選項目，但 API 頁面並不能證明它適合生產工作負載。

Hy3 是什麼，以及不是什麼

Hy3 是一個 295B 參數的 MoE 模型，每個 token 有 21B 個啟用參數。官方的 Hy3 模型卡列出了 192 個專家，採用 top-8 routing、80 層 backbone、1 個 MTP layer、256K-token 的 context window，以及 Apache 2.0 授權。

那些數字描述的是一個為推理、程式撰寫、長時間對話以及使用工具的 agents 所設計的文字模型。它們並不會讓 Hy3 成為影像或 OCR 模型。若工作流程的關鍵輸入是掃描的發票、螢幕截圖、產品照片或圖表，那麼在使用 Hy3 之前，首先需要的是 vision 或 OCR 模型。保持這條界線清楚，可避免一個常見的架構錯誤：要求一個有能力的文字模型去還原它從未收到的資訊。

Tencent 將 Hy3 定位用於程式設計、辦公工作、財務建模、前端工作和遊戲開發。請將這些視為候選工作負載，而非通用排名。

閱讀基準測試聲明及其限制

騰訊的發布公告指出，一項由 270 位專家執行工作任務的盲測評估中，Hy3 得分為 4 分中的 2.67，而 GLM-5.1 得分為 4 分中的 2.51。同一來源還表示，Hy3 的 SWE-Bench Verified 準確率在 CodeBuddy、Cline 和 KiloCode 脚手架之間的變動不到 4 個百分點。這些都是騰訊公布的結果，並不代表在您的環境中，Hy3 一定能擊敗某個指定的競爭對手。

Artificial Analysis 是另一個模型層級測量的參考點。請將基準測試數值視為模型選擇的輸入，而不是應用層級驗收標準的替代品。

根據失敗成本選擇推理模式

Hy3 在其官方服務範例中提供 no_think、low 和 high 推理努力。選擇應該取決於錯誤答案的成本，而不是使用推理模型的光環。

工作負載	從以下開始	在升級前要衡量的項目
分類、從乾淨文本中抽取，或簡單路由	`no_think`	正確的標籤或欄位值、延遲，以及輸出 tokens
有限的程式碼變更、多規則摘要，或單一工具序列	`low`	測試通過率、有效的工具參數，以及人工編輯
多檔案除錯、具衝突約束的規劃，或數值推理	`high`	完成任務率、重試次數、總 tokens，以及審查時間

對有範圍的工作保持 no-think

no_think 是預設的直接回應模式。當來源本身已經結構化、答案有既定格式，而且較慢的回應不會帶來有用的推理時，這是正確的基準。例如，一個選擇單一文件化狀態並呼叫一個函式的支援流程，應先在此模式下測試。加入嚴格的 JSON schema，並拒絕包含額外欄位的回應，而不是寄望更長的推理鏈能修補含糊的合約。

當錯誤會改變下一個動作時，使用低或高推理

當模型必須協調多項規則，或對程式碼進行有界限的變更時，請切換為 low。將 high 保留給那些中間決策一旦失準就會導致昂貴重試的工作：跨檔案診斷失敗、選擇操作順序，或在呼叫工具之前檢查計算結果。

這種取捨是可衡量的。比較整個已完成的任務：請求延遲、輸出 token 數量、工具呼叫重試次數、測試失敗，以及審核人員花在修正答案上的分鐘數。看起來更深思熟慮、但卻讓 token 數量加倍、卻沒有縮短審核時間的模式，並不是更適合生產環境的設定。

在採用 Hy3 之前，先進行四部分 API 試用

這個試驗所建立的是針對你的系統的證據，而不是一般性的模型判定。請使用真實但非敏感的任務。在執行模型之前，先固定提示、schema 和通過標準，這樣你就不會在看完答案後才改變評判標準。

使用最小化的自架呼叫驗證請求路徑

以下範例遵循 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)

在評估複雜的 agent 之前，先讓這個簡單的呼叫正常運作。這能將認證、端點、模板或模型名稱的問題，與模型品質問題區分開來。針對每次試驗，記錄 provider、model revision（若可用）、reasoning mode、timestamp、input tokens、output tokens，以及經過時間。

使用你的真實結構描述測試結構化輸出與工具呼叫

工具調用不應被評分為「模型選擇了一個合理的動作」。請傳送明確的 schema，並在您的應用程式中驗證返回的參數。這是一段 OpenAI 風格的請求片段；在依賴之前，請先向提供者確認 tool 參數支援的確切情況。

{
  "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
        }
      }
    }
  ]
}

針對此請求，正確的工具決策是一次 get_incident 呼叫，其 incident_id 必須正好是 INC-1042。你的程式碼應在接觸下游系統之前，拒絕缺少欄位、格式錯誤的 JSON 引數字串，或未預期的工具。請檢查五件事：

所選工具適用於此任務。
每個必填參數都已提供且型別正確。
ID、日期與金額皆來自所提供的上下文，而非憑空編造。
模型會針對缺少的必填值進行詢問，而不是自行猜測。
工具錯誤會導致有限次的修正或升級處理路徑，而不是陷入迴圈。

執行足夠多的範例，以涵蓋有效輸入、含糊不清的請求、缺少欄位，以及一個故意失敗的工具回應。順利情況下穩定輸出 JSON 很有用；而當系統拒絕某個引數時仍能穩定運作，才是防止 agent 為操作人員製造額外工作的關鍵。

測試長上下文以保留限制，而非標題長度

Hy3 的 256K 上下文只有在相關事實能以你的提示格式保留下來時才有價值。請根據具代表性的 repository、policy bundle，或客戶歷史對話串建立一個測試。將幾個具體限制放在不同位置，加入逼真的干擾項，並要求答案必須引用或轉換這些限制。

評估精確檢索、對每個具名約束的遵循、未經支援的主張，以及總請求成本。然後在啟用生產檢索層的情況下重複一次。這樣可以顯示失敗究竟屬於模型、分塊、檢索排序，還是提示組裝程式碼。只傳入一份大型貼上的文件，並不足以成為關閉防護措施的證據。

測試可證明遷移合理性的工作負載

選擇一項任務，其中更好的模型結果具有明確的商業價值：修復跨多個檔案的失敗測試、從冗長的政策中提取義務，或使用工具完成多步驟的內部操作。在相同的超時與審核規則下，比較目前的生產流程與 Hy3。

記錄已完成任務率、p50 和 p95 延遲、輸入與輸出 tokens、工具重試次數，以及審核者修正時間。這也是混合社群回饋開始發揮作用的地方。不要僅憑「Hy3 是特別優秀」或「令人失望」這類抽象說法來判斷。請根據你實際願意付費自動化的任務來做決定。

託管 API 還是自架？

在評估模型、流量仍不確定，或你的團隊尚未具備所需的 GPU 容量時，請先使用託管 API。這能縮短通往上述測試的路徑，並將供應商可用性與你的應用程式邏輯分離。

只有在您有明確的控制、隱私、容量或延遲需求，且具備支援它的基礎架構時，才應自行架設。官方模型卡建議使用八張 H20-3e GPU 或其他大記憶體 GPU 來提供 Hy3 服務，並搭配 vLLM 或 SGLang 配方。那是騰訊對生產環境服務的建議，並不表示消費級筆電能提供等效部署。在將開放權重視為免費基礎架構之前，請先衡量 GPU 預留、升級、監控、批次處理，以及值班維運責任的成本，並與託管帳單相比較。

選擇此路徑	何時是較佳選擇	需要規劃的主要風險
Hosted API	快速評估、需求變動、平台團隊規模小	供應商模型 ID、限制、可用性和價格可能會變動
Self-hosted Hy3	對資料控制有強烈需求，或由經驗豐富的營運人員支援的持續性大量使用	高記憶體硬體、服務提供複雜度、容量規劃與營運支援

定價與供應情況的變化速度可能比權重還快

騰訊公布 Hy3 API 定價為每百萬輸入 tokens 1 人民幣、每百萬輸出 tokens 4 人民幣，以及每百萬快取輸入 tokens 0.25 人民幣，時間為 7 月 6 日。請將此作為有日期的參考點，然後在正式上線前確認實際的端點價格。供應商的免費方案、入門額度或暫時性的免費模型別名，只代表可用於實驗，並不代表永久性的單位成本承諾。

若要進行簡單的成本估算，100 次每日請求，每次包含 20K 輸入 token 和 1K 輸出 token，總共會使用 2M 輸入 token 和 0.1M 輸出 token。按騰訊公布的參考價格計算，這相當於每天 2.4 RMB，或 30 天約 72 RMB。若全部 2M 輸入 token 都符合快取定價，則同樣的計算結果是每天 0.9 RMB。這只是僅依 token 的估算：不包含供應商加價、免費額度限制、重試，以及您的應用程式新增的任何上下文。

在規劃試用預算時，請將檢索到的上下文、系統提示、工具定義、重試，以及由所選推理設定產生的輸出納入考量。當關鍵輸入為視覺內容、必須採用輕量級本地部署，或應用程式無法驗證工具引數及後續副作用時，請不要選擇 Hy3。

對於需要大型上下文視窗、可設定推理以及開放權重的文字密集型 agent，Hy3 是一個值得評估的合理模型。只有在它能以可接受的總成本降低修正時間時，才保留它。

常見問題

Hy3 是多模態嗎？

不是。Hy3 是一個文字輸入、文字輸出的模型。當任務是從圖片、掃描件或螢幕截圖開始時，請使用 vision 或 OCR 模型。

什麼是 Hy3 上下文視窗？

騰訊的模型卡列出 256K token 的上下文窗口。長上下文限制並不保證能檢索到或遵循相關事實，因此請使用具代表性的來源資料來驗證。

我應該從哪一種 Hy3 推理模式開始？

對於有界且對延遲敏感的工作，先使用 no_think。只有在任務的失敗成本與實測改善足以證明額外的 token 和時間是值得的時候，才改用 low 或 high。

我可以自行架設 Hy3 嗎？

是。Tencent 提供 vLLM 和 SGLang 部署指引，並建議使用八張大記憶體 GPU 來提供服務。自架應根據容量與營運決策來決定，而不僅僅是依據開放權重授權。

免費的 Hy3 API 是永久的定價方案嗎？

不。免費存取取決於供應商，且可能會終止或變更限制。在承諾生產工作流程之前，請先確認目前的供應商條款以及付費費率。