腾讯的 Hy3 模型已在 Novita AI 上架，模型 ID 为 tencent/hy3，提供兼容 OpenAI 的 chat/completions 端点、256K 上下文窗口，并支持函数调用、结构化输出及三种推理模式。本快速入门将涵盖开发者所需的关键设置：配置客户端、发送首次请求、使用函数调用、启用推理功能，以及在开始构建前了解速率限制。
何时使用本快速入门
当你需要在编写额外代码之前，向 Hy3 发送一个可正常运行的请求时，请参考本指南。它涵盖了一条实用的路径：选择模型 ID、完成身份验证、发送一个测试请求，然后根据你的工作负载需求扩展到函数调用或推理功能。
Hy3 的架构 —— 总计 295B 参数、21B 活跃参数的 MoE 模型 —— 旨在平衡规模下的质量与效率。在以下场景中值得考虑使用：
- 长上下文文档处理（256K 窗口单次调用可容纳约 20 万词）。
- 受益于大活跃参数预算的多轮对话。
- 需要工具调用和可靠参数格式化的智能体任务。
- 覆盖大型代码库且无需分块的编程辅助。
本指南仅涵盖通过 Novita AI 进行 API 集成的路径，不涉及自行部署、微调或迁移至其他推理后端。
第一步：获取你的 Novita API 密钥
创建一个 Novita AI 账户，并导航至控制台的 API 密钥部分。生成一个密钥并将其存储在环境变量中。请勿将其放入客户端代码、前端捆绑包或公共仓库中。
export NOVITA_API_KEY="your_api_key"
如果你在其他项目中已使用 OpenAI Python SDK 或兼容 OpenAI 的客户端，此处的设置完全相同 —— 只需更改 base URL 和模型名称，其他无需改动。
第二步：确认模型 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 参考 则记录了完整的请求和响应格式。
第三步：查看定价、限制及模型详情
来自 Novita AI Hy3 模型页面 的当前值：
| 字段 | 值 |
|---|---|
| 显示名称 | Hy3 |
| API 模型 ID | tencent/hy3 |
| 模型系列 | Hunyuan |
| 架构 | MoE，总计 295B / 活跃 21B |
| 端点 | chat/completions |
| 输入模态 | 文本 |
| 输出模态 | 文本 |
| 上下文窗口 | 262,144 个 token |
| 最大输出 token 数 | 262,144 个 token |
| 功能特性 | 无服务器、函数调用、结构化输出、推理 |
| 输入价格 | 标价为 $0 / M token（请查看模型页面确认当前费率） |
| 输出价格 | 标价为 $0 / M token（请查看模型页面确认当前费率） |
速率限制根据账户层级（T1–T5）进行调整，并以每分钟请求数（RPM）和每分钟 token 数（TPM）来衡量。当前层级阈值和限制详见 Novita AI 速率限制文档。
定价和速率限制可能随时变更。在确定任何成本估算之前，请查看 Hy3 模型页面 和 Novita AI 定价页面。
第四步：发送你的第一个请求
从一个简单的文本请求开始，以确认身份验证、模型路由和响应解析。保持提示简短，以便测试连接性而非输出质量。
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": "你是一位简洁的技术助手。"
},
{
"role": "user",
"content": "请用三句话描述 MoE 与密集 Transformer 架构之间的主要权衡。"
}
],
"max_tokens": 256,
"temperature": 0.3
}'
成功的响应将返回标准的聊天补全格式：一个 choices 数组、一条包含 content 的消息、模型和创建时间元数据，以及一个包含提示、补全和总 token 数的 usage 对象。
通过此冒烟测试可以验证：
- API 密钥有效且授权标头格式正确。
- 模型 ID
tencent/hy3被接受，未返回 404 或模型未找到错误。 - 你的客户端能够解析
choices[0].message.content。 - Token 使用情况已记录，以便从第一次请求开始监控成本。
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": "你是一位简洁的技术助手。"},
{
"role": "user",
"content": "请用三句话描述 MoE 与密集 Transformer 架构之间的主要权衡。",
},
],
max_tokens=256,
temperature=0.3,
)
print(response.choices[0].message.content)
print("使用的 token 数：", response.usage.total_tokens)
第五步：解读响应
响应遵循标准的 OpenAI 聊天补全格式：
{
"id": "chatcmpl-...",
"object": "chat.completion",
"created": 1751000000,
"model": "tencent/hy3",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "MoE 模型仅激活其总参数中的一小部分..."
},
"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": "搜索产品知识库以解答客户问题。",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "客户的问题或要搜索的主题。",
},
"max_results": {
"type": "integer",
"description": "返回的最大结果数。默认为 5。",
},
},
"required": ["query"],
},
},
}
]
response = client.chat.completions.create(
model="tencent/hy3",
messages=[
{"role": "system", "content": "你是一位客户支持助手。请使用搜索工具查找相关答案。"},
{
"role": "user",
"content": "过去 30 天内购买的电子产品退货政策是什么？",
},
],
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"工具：{call.function.name}")
args = json.loads(call.function.arguments)
print(f"参数：{args}")
else:
print(message.content)
当模型返回工具调用时，你的应用程序执行该函数，然后将结果发送回对话中：
# 执行你的搜索函数后，将结果发送回去
tool_result = "凭原始收据 30 天内可退货。电子产品必须未开封。"
follow_up = client.chat.completions.create(
model="tencent/hy3",
messages=[
{"role": "system", "content": "你是一位客户支持助手。"},
{"role": "user", "content": "过去 30 天内购买的电子产品退货政策是什么？"},
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": "你是一位文档分析助手。请提供具体且有引用的回答。",
},
{
"role": "user",
"content": f"以下是文档：\n\n{document_text}\n\n请总结本文档中的关键义务和截止日期。",
},
],
max_tokens=1024,
temperature=0.2,
)
print(response.choices[0].message.content)
监控响应中的 usage.prompt_tokens，以跟踪你的输入消耗了多少 token。对于反复发送相同系统提示或文档前导部分的工作负载，速率限制和成本规划取决于实际的提示 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 会影响成本和延迟。
首次响应缓慢：大型模型部署在首次请求时可能会经历短暂的冷启动延迟。后续对同一端点的请求通常更快。如果延迟是硬性要求，请在投产前在目标并发级别测试吞吐量。
工具调用返回意外的参数：修改你的工具架构。为每个参数添加更具体的描述，在描述字段中包含示例值，并显式列出必填字段。先从简化的架构开始测试，然后逐步增加复杂性。
常见问题
Hy3 在 Novita AI 上可用吗？
是的。Novita AI 将 Hy3 列为无服务器 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 模型页面将推理列为一项功能。使用 tencent/hy3 启用推理的具体请求参数在当前 Novita 文档中尚未确认。在将推理行为构建到生产环境之前，请查看 Novita AI 聊天补全 API 参考 并进行一次测试调用以验证参数格式。
Hy3 接受哪些输入？
Hy3 仅接受文本输入。Novita AI 模型页面未列出图像或视频模态。
Hy3 的架构是什么？
Hy3 采用 MoE（混合专家）架构，总计 295B 参数，每次前向传播有 21B 活跃参数。这使得它能够以比同等质量的密集模型更低的计算成本处理大型上下文请求。
如何获得更高的速率限制？
速率限制根据账户层级进行调整。当前层级阈值和限制详见 Novita AI 速率限制文档。联系 Novita AI 支持了解升级选项。
