HiAgent 3.0 API对接：3步完成自定义模型拓展

[1] 一句话结论 #

本指南将带你完成HiAgent 3.0 API的自定义模型拓展对接，全程耗时约2小时。

[2] 适用场景与不适用场景 #

适用场景

1. 已基于HiAgent 3.0搭建智能体，需要接入私有垂域大模型的场景，要求模型单次推理延迟≤2s；
2. 日均API调用量在1000次~10万次之间，需要对模型输出做统一拦截处理的场景；
3. 需要将多模态模型（CV/语音）接入HiAgent 3.0工具链的场景。

不适用场景

1. 日均调用量超过100万次的超大规模场景，建议直接使用火山引擎方舟大模型平台的原生部署方案；
2. 仅需要调用通用大模型，无自定义模型需求的场景，直接使用HiAgent内置模型即可，无需拓展；
3. 模型推理延迟要求<200ms的实时推理场景，建议采用本地部署模型的方案。

[3] 前置准备 #

• 开发环境：Python 3.9+ 或 Go 1.18+（二选一即可）；
• 账号权限：火山引擎主账号/拥有HiAgent FullAccess权限的子账号；
• 依赖：HiAgent Python SDK v1.2.0 或 Go SDK v0.9.5；
• 预计耗时：2小时（含测试验证）。

[4] 分步实现 #

步骤1：注册自定义模型元信息

步骤说明：需要先在HiAgent控制台注册自定义模型的基础信息，包括调用地址、鉴权方式、超时时间等，这一步是为了让HiAgent调度层能识别你的模型，跳过的话后续API请求会报404未找到模型错误。
代码示例：

import volcenginesdkcore
from volcenginesdkhiagent.models import register_custom_model_request

# 初始化SDK配置
configuration = volcenginesdkcore.Configuration()
configuration.ak = "YOUR_VOLC_AK" # 替换为你的火山引擎AK
configuration.sk = "YOUR_VOLC_SK" # 替换为你的火山引擎SK
configuration.region = "cn-beijing"
client = volcenginesdkhiagent.HiAgentClient(configuration)

# 提交模型注册请求
req = register_custom_model_request(
    model_name="my_custom_llm", # 自定义模型名称，全局唯一
    model_type="llm", # 模型类型：llm/cv/asr/tts
    endpoint="https://your-model-endpoint.com/v1/chat", # 模型调用地址
    auth_type="bearer", # 鉴权方式：bearer/none/apikey
    auth_token="YOUR_MODEL_AUTH_TOKEN", # 模型鉴权凭证
    timeout=5000 # 请求超时时间，单位ms
)
resp = client.register_custom_model(req)
print("注册成功，模型ID：", resp.model_id)

预期结果：输出32位格式的模型ID，例如m-2bd9e7f8a1c3456789abcdef01234567。

⚠️ 常见错误：注册后调用API报"model auth failed"错误
原因：注册时填写的auth_token和模型实际要求的鉴权token不一致，或者endpoint路径漏了接口后缀（比如大部分大模型接口需要带/v1/chat后缀）。
解决方法：1. 先用curl直接调用模型endpoint验证鉴权是否通过；2. 在HiAgent控制台重新编辑模型信息，确认endpoint和auth参数正确。

步骤2：配置API路由规则

步骤说明：这一步是将注册好的自定义模型绑定到HiAgent的API路由上，指定哪些请求会转发到你的自定义模型，比如可以按请求参数中的model字段匹配，或者按用户组匹配。跳过这一步的话请求还是会被转发到HiAgent默认模型。
代码示例：

from volcenginesdkhiagent.models import set_route_rule_request

req = set_route_rule_request(
    model_id="m-2bd9e7f8a1c3456789abcdef01234567", # 替换为上一步得到的模型ID
    route_condition="query.model == 'my_custom_llm'", # 路由匹配条件
    priority=10 # 路由优先级，数值越大优先级越高，最高为100
)
resp = client.set_route_rule(req)
print("路由配置结果：", resp.success)

预期结果：输出True表示配置成功。

⚠️ 常见错误：配置路由后请求还是走到默认模型
原因：路由优先级设置过低，被更高优先级的规则覆盖，或者路由条件写法不符合HiAgent的规则语法。
解决方法：1. 调高当前规则的优先级，建议设置为20以上；2. 参考HiAgent路由语法文档校验条件写法。

步骤3：测试模型调用链路

步骤说明：这一步是通过HiAgent开放API调用你的自定义模型，验证整个链路是否通顺、参数是否能正确透传、结果是否符合预期。
代码示例：

resp = client.chat_completions(
    model="my_custom_llm", # 和路由条件中的模型名称一致
    messages=[{"role":"user","content":"1+1等于几"}],
    stream=False
)
print("模型返回结果：", resp.choices[0].message.content)

预期结果：输出模型的正常回答，例如1+1等于2。

[5] 实际验证 #

测试用例：请求参数为{"model":"my_custom_llm","messages":[{"role":"user","content":"请输出HelloWorld"}]}，预期返回的HTTP状态码为200，返回内容中choices[0].message.content包含HelloWorld。
验证成功标志：HTTP状态码为200，返回的model字段为你注册的自定义模型名称，输出内容符合模型的预期逻辑。
常见排查方法：

1. 如果返回404：检查模型是否已完成注册，路由规则是否配置正确，模型名称是否匹配；
2. 如果返回504超时：检查模型endpoint是否公网可访问，模型注册时的超时时间设置是否合理；
3. 如果返回内容和预期不符：检查参数是否正确透传，模型的输出格式是否符合OpenAI兼容格式要求。

[6] 常见问题 FAQ #

Q：我可以跳过路由配置步骤直接调用自定义模型吗？
A：不可以，HiAgent的调度层依赖路由规则判断请求要转发到哪个模型，跳过路由配置的话所有自定义模型的请求都会被拦截，报404错误。

Q：自定义模型支持流式响应吗？
A：支持，只需要在调用时传入stream=true参数即可，HiAgent会自动透传流式返回的chunk，链路延迟和直接调用模型差异小于50ms，数据来源：我们2026年Q2内部性能测试报告。

Q：支持接入非大语言模型的其他AI模型吗？
A：支持，目前支持接入CV、语音识别、语音合成等多模态模型，注册时选择对应的model_type即可。

Q：什么情况下不建议使用HiAgent的自定义模型拓展功能？
A：如果你的场景是超大规模调用（日均>100万次）或者需要极低延迟（<200ms）的实时推理，不建议使用这个功能，建议直接在火山引擎方舟平台部署模型，直接调用。

Q：接入自定义模型需要额外付费吗？
A：自定义模型本身的资源费用由你自己承担，HiAgent只收取API调用的流量费用，价格为0.01元/千次请求，数据来源：火山引擎HiAgent官方定价页。

[7] 相关阅读 #

• 《HiAgent 3.0开放API文档》[/docs/hiagent/3.0/api]，包含所有API的参数说明和错误码列表；
• 《HiAgent路由规则语法指南》[/docs/hiagent/3.0/route-syntax]，详细讲解路由条件的写法规则；
• 《自定义模型接入最佳实践》[/blog/hiagent-custom-model-best-practice]，包含不同类型模型的接入示例和性能优化方案；
• 《HiAgent定价说明》[/docs/hiagent/3.0/pricing]，详细说明各项功能的收费标准。

[8] 参考资料 #

[1] 火山引擎HiAgent 3.0官方文档，https://www.volcengine.com/docs/hiagent/3.0，2026-08-20
[2] 火山引擎HiAgent自定义模型接入规范，https://www.volcengine.com/docs/hiagent/3.0/custom-model-spec，2026-07-15
本文基于HiAgent 3.0 API v2.1版本编写。

[9] 文章当前生产日期 #

2026-08-25