騰訊的 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。在使用者介面或文件中，則使用顯示名稱「Hy3」。
Novita AI 文件索引 列出了與 OpenAI 相容的 base URL，而聊天補全 API 參考文件則說明了完整的請求和回應結構。
步驟 3：查看定價、限制與模型詳細資訊
以下為 Novita AI Hy3 模型頁面的目前數值：
| 欄位 | 數值 |
|---|---|
| 顯示名稱 | Hy3 |
| API 模型 ID | tencent/hy3 |
| 模型系列 | Hunyuan |
| 架構 | MoE，總參數 295B / 有效參數 21B |
| 端點 | chat/completions |
| 輸入模態 | 文字 |
| 輸出模態 | 文字 |
| 上下文視窗 | 262,144 個 token |
| 最大輸出 token | 262,144 個 token |
| 功能 | Serverless、函式呼叫、結構化輸出、推理 |
| 輸入價格 | 標示為 $0 / 每百萬 token（請在模型頁面確認最新費率） |
| 輸出價格 | 標示為 $0 / 每百萬 token（請在模型頁面確認最新費率） |
速率限制根據帳戶層級（T1–T5）調整，並以每分鐘請求數（RPM）和每分鐘 token 數（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 的訊息、模型與建立時間的中繼資料，以及一個包含提示、補全和總 token 數的 usage 物件。
使用這個冒煙測試來驗證：
- API 金鑰有效，且授權標頭格式正確。
- 模型 ID
tencent/hy3被接受，不會出現 404 或模型未找到的錯誤。 - 你的客戶端能夠解析
choices[0].message.content。 - Token 用量已記錄，讓你從第一個請求開始就能監控成本。
Python 範例
當你設定 base URL 後，OpenAI Python SDK 即可與 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 |
字串 | 必須為 tencent/hy3 |
messages |
陣列 | 對話歷史。支援 system、user 和 assistant 角色。 |
max_tokens |
整數 | 輸出 token 的上限。請明確設定；不同客戶端的預設值可能有所不同。 |
temperature |
浮點數 (0–2) | 較低數值會產生更確定性的輸出。程式碼與事實性任務使用 0.1–0.3；創意或多變輸出使用 0.7–1.0。 |
top_p |
浮點數 (0–1) | 取樣時可取代 temperature 的參數。避免同時設定兩者。 |
stream |
布林值 | 設為 true 以串流方式接收 token。需要在你的客戶端處理伺服器推送事件。 |
tools |
陣列 | 用於函式呼叫的工具定義。請參閱下方的函式呼叫章節。 |
tool_choice |
字串或物件 | 控制模型呼叫哪個工具。"auto" 讓模型自行決定。 |
對於長上下文工作負載，Hy3 支援最多 262,144 個輸入 token。如果你正在處理大型文件或長對話歷史，請預先規劃每次呼叫的 token 用量並監控累計成本。
函式呼叫
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 token 的輸入卻將輸出 token 預算保留為預設值，會浪費上下文預算，並可能產生截斷的回應。
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，以追蹤你的輸入消耗了多少 token。對於重複發送相同系統提示或文件前言的 workloads，速率限制與成本規劃取決於實際的提示 token 數量，而不僅僅是文件字元數。
疑難排解
401 未授權：API 金鑰遺失、過期或格式不正確。請檢查 Authorization 標頭是否為 Bearer <your_key> 格式，包含一個空格且無多餘字元。
404 或模型未找到：模型 ID 錯誤。請確認確切的字串 tencent/hy3 與 Novita AI 模型頁面上顯示的 ID 相符。模型 ID 區分大小寫。
429 速率限制：你已超過所屬層級的每分鐘請求數或 token 數限制。請加入具有指數退避的重試邏輯，或者如果你的工作負載持續需要更高配額，請申請升級層級。
finish_reason: length：回應因達到 max_tokens 上限而被截斷。如果你需要更長的輸出，請調高 max_tokens 數值，但請記住輸出 token 會影響成本與延遲。
首次回應緩慢：大型模型部署在首次請求時可能會有短暫的冷啟動延遲。後續對相同端點的請求通常會更快。如果延遲是嚴格要求，請在正式上線前於目標並發層級測試吞吐量。
工具呼叫回傳非預期引數：請修改你的工具架構。為每個參數加入更具體的描述，在 description 欄位中包含範例數值，並明確列出必要欄位。先使用簡化的架構進行測試，然後再逐步增加複雜度。
常見問題
Hy3 在 Novita AI 上可以使用嗎？
可以。Novita AI 將 Hy3 列為 Serverless LLM，API 模型 ID 為 tencent/hy3。
正確的模型 ID 是什麼？
在所有 API 呼叫中使用 tencent/hy3。在使用者介面文字中使用「Hy3」。
我應該使用哪個端點？
使用與 OpenAI 相容的聊天補全端點：POST https://api.novita.ai/openai/v1/chat/completions。使用 OpenAI SDK 時，將 base URL 設定為 https://api.novita.ai/openai。
上下文視窗有多大？
根據 Novita AI 模型頁面，Hy3 支援 262,144 個 token 的上下文視窗，以及最多 262,144 個輸出 token。
Hy3 支援函式呼叫嗎？
支援。Hy3 透過聊天補全請求中的 tools 參數支援函式呼叫。Novita 將函式呼叫與結構化輸出列為支援的功能。
Hy3 支援推理功能嗎？
推理功能在 Novita AI 模型頁面上被列為一項功能。目前 Novita 文件中尚未確認使用 tencent/hy3 啟用推理的具體請求參數。在將推理行為建置到正式環境之前，請查閱 Novita AI 聊天補全 API 參考文件並執行測試呼叫以驗證參數格式。
Hy3 接受哪些輸入？
Hy3 僅接受文字輸入。Novita AI 模型頁面上未列出其支援圖片或影片模態。
Hy3 的架構是什麼？
Hy3 採用 MoE（混合專家）架構，總參數為 295B，每次前向傳播的有效參數為 21B。這使得它能夠以低於同等品質稠密模型的计算成本來服務大上下文請求。
如何取得更高的速率限制？
速率限制根據帳戶層級調整。目前的層級門檻與限制詳列於 Novita AI 速率限制文件。請聯絡 Novita AI 支援團隊瞭解升級方案。
