Hy3 API 指南：推理、工具调用与长上下文

Hy3 是一个仅文本的 MoE 模型，适用于编码、推理、长上下文任务和 agents。对于首次集成，请使用托管的 OpenAI 兼容端点，发送标准的 Chat Completions 请求，并评估你真正会自动化的那一个工作流。在它遵循你的工具 schema 并保留你长输入中重要的约束之前，不要将其标准化采用。

以下提供商详情于 2026 年 7 月 14 日核实。DeepInfra 将该模型文档化为其 OpenAI 兼容的 Chat Completions 端点上的 tencent/Hy3。SiliconFlow 也在相同的模型 ID 下列出 Hy3。提供商的价格、限制和别名可能会变化，因此在上线前请先确认实时的提供商页面。

从托管的 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 结构。请按如下方式解析答案和计费字段：

{
  "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] 结束的服务器发送事件。

表格中的提供商选项是刻意收窄的。它们是经过验证的公共访问路径，而不是价格排名。

腾讯于2026年7月6日发布的公告将 Hy3 介绍为一个开放权重的 Mixture-of-Experts 模型。其官方定价公告和 model card 使其成为托管评估的候选对象，但 API 页面并不能证明它适合生产工作负载。

Hy3 是什么，以及它不是什么

Hy3 是一个拥有 295B 参数的 MoE 模型，每个 token 激活 21B 参数。官方的 Hy3 model card 列出了 192 个专家，采用 top-8 routing，80 层 backbone，1 个 MTP layer，256K-token context window，以及 Apache 2.0 license。

这些数字描述的是一个为推理、编码、长时间对话以及使用工具的代理而设计的文本模型。它们并不意味着 Hy3 是一个图像或 OCR 模型。其关键输入是扫描发票、屏幕截图、产品照片或图表的工作流，在需要 Hy3 之前，首先需要一个视觉或 OCR 模型。保持这条边界清晰，可以避免一个常见的架构错误：让一个能力强大的文本模型去恢复它从未接收到的信息。

腾讯将 Hy3 定位用于编码、办公、财务建模、前端工作和游戏开发。请将这些视为候选工作负载，而不是通用排名。

阅读基准测试声明及其限制

腾讯的发布公告称，一项由 270 名专家参与工作任务的盲测评估显示，Hy3 得分为 4 分中的 2.67，GLM-5.1 得分为 4 分中的 2.51。该来源还表示，Hy3 在 CodeBuddy、Cline 和 KiloCode scaffolds 上的 SWE-Bench Verified 准确率波动不超过 4 个百分点。这些结果均由腾讯报告，并不构成在你的环境中 Hy3 一定会击败某个指定竞品的独立保证。

Artificial Analysis 是另一个用于模型级测量的参考点。将基准测试数值视为模型选择的输入，而不是应用级验收标准的替代品。

根据失败成本选择推理模式

Hy3 在其官方服务示例中提供 no_think、low 和 high 推理强度。选择应取决于错误答案的代价，而不是使用推理模型的“光环”。

有限任务保持 no-think

no_think 是默认的直接响应模式。当源内容已经结构化、答案具有已知格式，并且更慢的响应不会带来有用的推理时，它就是合适的基准。例如，一个选择某个已记录状态并调用一个函数的支持工作流，应先在此模式下进行测试。添加严格的 JSON schema，并拒绝包含额外字段的响应，而不是指望更长的推理链能修复一个模糊的契约。

当错误会改变下一步操作时，使用低推理或高推理

当模型必须协调多条规则或对代码进行有限范围的修改时，改用 low。将 high 保留用于那些中间决策稍有偏差就会导致代价高昂的重试的工作：跨文件诊断故障、选择操作顺序，或在调用工具前检查计算结果。

这种权衡是可衡量的。比较整个已完成的任务：请求延迟、输出 token 数量、工具调用重试、测试失败次数，以及审阅者花在修正答案上的分钟数。一个看起来更周到、但 token 数量翻倍却没有减少审阅时间的模式，并不是更适合生产环境的设置。

在采用 Hy3 之前，先进行四部分 API 试用

此试验为你的系统而非通用模型结论创建证据。使用真实但非敏感的任务。在运行模型之前冻结 prompts、schemas 和通过标准，这样你就不会在读完答案后更改评判标准。

通过最小化的自托管调用验证请求路径

以下示例遵循 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 之前，先让这个简单的调用正常工作。这样可以将认证、端点、模板或模型名称问题与模型质量问题区分开来。记录每次试验的提供方、模型修订版（如有）、推理模式、时间戳、输入 token、输出 token 以及耗时。

使用你的真实 schema 测试结构化输出和工具调用

工具调用不应被评为“模型选择了一个合理的操作”。请发送一个明确的 schema，并在你的应用中验证返回的参数。这是一个 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
        }
      }
    }
  ]
}

对于此请求，正确的工具决策意味着一次 get_incident 调用，其 incident_id 必须恰好是 INC-1042。你的代码应在接触下游系统之前，拒绝缺失字段、格式错误的 JSON 参数字符串或意外的工具。检查五项内容：

1. 所选工具允许用于该任务。

2. 所有必需参数都已提供且类型正确。

3. ID、日期和金额均来自所提供的上下文，而不是凭空编造的。

4. 模型会请求缺失的必填值，而不是自行猜测。

5. 工具错误会导致有限的修复或升级路径，而不是陷入循环。

运行足够多的示例，以涵盖有效输入、含糊不清的请求、缺失字段，以及一个故意失败的工具响应。顺利情况下可靠的 JSON 很有用；而当系统拒绝某个参数时，可靠的行为才是防止代理给操作员制造额外工作的关键。

测试长上下文以保持约束，而不是标题长度

Hy3 的 256K 上下文只有在相关事实能够保留在你的提示格式中时才有价值。请基于一个有代表性的代码库、政策包或客户历史线程构建一个测试。在不同位置加入几个具体约束，添加真实的干扰项，并要求给出一个必须引用或转换这些约束的答案。

对精确检索、对每一项命名约束的遵循、未经支持的主张以及总请求成本进行评分。然后在启用生产检索层的情况下重复评估。这可以暴露故障究竟属于模型、分块、检索排序，还是提示组装代码。仅凭传入一大段粘贴文档，并不足以证明可以关闭护栏。

测试能证明迁移合理性的工作负载

选择一个任务，其中更好的模型结果具有明确的业务价值：修复跨多个文件的失败测试、从一份较长的政策中提取义务，或使用工具完成一个多步骤的内部操作。在相同的超时和审核规则下，比较当前的生产路径和 Hy3。

记录已完成任务率、p50 和 p95 延迟、输入和输出 token、工具重试次数以及审阅者纠正时间。这也是混合社区反馈开始变得有用的地方。不要根据“Hy3 非常出色”或“Hy3 令人失望”这样的抽象说法来判断。要根据你实际愿意花钱自动化的任务来判断。

托管 API 还是自托管？

在评估模型、流量仍不确定，或者你的团队尚未运营所需的 GPU 容量时，先使用托管 API。这样可以缩短到上述测试的路径，并将提供商可用性与您的应用逻辑分离。

只有在您有明确的控制、隐私、规模或延迟方面的理由，并且具备相应基础设施来支持时，才进行自托管。官方模型卡建议使用八块 H20-3e GPU 或其他大显存 GPU 来部署 Hy3，并提供 vLLM 或 SGLang 的配置方案。这是腾讯的生产环境部署建议，并不意味着一台消费级笔记本能够提供等效的部署。将 GPU 预留、升级、监控、批处理和值班维护的成本与托管服务账单进行比较后，再把开源权重视为免费基础设施。

定价和可用性可能比权重变化得更快

腾讯列出了 Hy3 API 定价：输入 tokens 每百万 1 元人民币，输出 tokens 每百万 4 元人民币，缓存输入 tokens 每百万 0.25 元人民币，时间是 7 月 6 日。请将此作为一个带日期的参考点，然后在上线前确认实际端点价格。提供方的免费套餐、试用额度或临时免费的模型别名，表示的是实验可用性，而不是永久的单位成本承诺。

对于一个简单的成本估算，100 次每日请求，每次包含 20K 输入 tokens 和 1K 输出 tokens，总共会使用 2M 输入 tokens 和 0.1M 输出 tokens。按照腾讯公布的参考价格，这相当于每天 2.4 RMB，或 30 天约 72 RMB。如果这 2M 输入 tokens 全部符合缓存定价条件，那么同样的计算结果是每天 0.9 RMB。这只是基于 token 的估算：不包括提供商加价、免费额度限制、重试，以及您的应用添加的任何上下文。

在为试用版制定预算时，请将检索到的上下文、system prompt、tool definitions、重试，以及所选 reasoning setting 产生的输出都计算在内。如果关键输入是视觉内容、必须进行轻量级本地部署，或者应用无法验证 tool arguments 和下游副作用，请不要选择 Hy3。

对于需要大上下文窗口、可配置推理以及开放权重的文本密集型 agent，Hy3 是一个值得评估的合理模型。只有在它能以可接受的总成本减少修正时间时，才保留它。

常见问题

Hy3 是多模态的吗？

不。Hy3 是一个文本输入、文本输出模型。当任务以图像、扫描件或截图开始时，请使用视觉或 OCR 模型。

什么是 Hy3 上下文窗口？

腾讯的模型卡列出了 256K 令牌的上下文窗口。长上下文限制并不保证能够检索到或遵循相关事实，因此请使用具有代表性的源材料进行验证。

我应该从哪种 Hy3 推理模式开始？

对于有边界、对延迟敏感的工作，先使用 no_think。只有在任务的失败成本和测得的改进足以证明额外的 token 和时间开销合理时，才切换到 low 或 high。

我可以自行托管 Hy3 吗？

是的。腾讯提供 vLLM 和 SGLang 部署指导，并建议使用八块大显存 GPU 进行服务部署。自托管应基于容量和运维决策，而不应仅仅依据开放权重许可。

免费的 Hy3 API 是永久的定价方案吗？

不。免费访问取决于提供商，可能会结束或更改限制。在投入生产工作流之前，请确认当前提供商条款和付费费率。