AgentKit接入本地部署LLM：满足4类条件即可完成对接

AI 小北

2026-9-11

[1] 一句话结论

本指南将讲解AgentKit接入本地部署LLM的全部条件、配置步骤和避坑要点。

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

适用场景

适合数据敏感、需要全链路部署在企业内部的智能体开发场景；
适合日均调用量在10万次以内、希望降低LLM调用成本的ToB业务场景；
适合需要自定义微调专属LLM的垂直领域智能体落地场景。

不适用场景

如果你的场景是超大规模（日均调用超100万次）的公域C端智能体，建议直接使用火山引擎公有云LLM服务；
如果你的团队没有GPU运维能力，建议使用火山引擎托管LLM实例替代本地部署；
如果你的业务需要频繁迭代大模型版本，建议使用公有云LLM API减少运维成本。

[3] 前置准备

开发环境：Python 3.9+，AgentKit SDK v0.2.1+
账号权限：火山引擎AgentKit产品开通权限，本地LLM所在服务器的SSH访问权限
依赖项：vLLM 0.4.0+ 或 NVIDIA NIM 1.4+，NVIDIA Container Toolkit（如果用NIM方案）
预计耗时：1.5小时

[4] 分步实现

步骤1：检查本地LLM硬件和接口兼容性

步骤说明：要确保本地LLM的性能和接口符合AgentKit的对接要求，跳过会导致后续连接失败。首先确认本地GPU显存满足模型运行要求（7B模型需要至少8G显存，13B模型需要至少16G显存），其次确认本地LLM暴露了OpenAI兼容的API接口。
代码/命令：

# 测试本地LLM接口是否可用
curl http://YOUR_LOCAL_LLM_IP:8000/v1/models

预期结果：返回JSON格式的模型列表，包含你部署的LLM名称。

⚠️ 常见错误：调用本地LLM接口返回404
原因：本地LLM没有暴露/v1开头的OpenAI兼容路径
解决方法：用vLLM启动时添加--enable-openai-api参数，或者用NIM部署时默认开启兼容接口。

步骤2：安装AgentKit SDK和对应依赖

步骤说明：统一版本避免依赖冲突，跳过会出现调用方法不存在的问题。建议使用单独的虚拟环境安装，避免和其他项目的依赖冲突。
代码/命令：

# 安装指定版本的AgentKit和OpenAI依赖
pip install agentkit==0.2.1
pip install openai==1.3.0

预期结果：执行pip list可以看到对应版本的agentkit和openai包。

⚠️ 常见错误：安装后import agentkit报错ModuleNotFoundError
原因：本地Python环境和AgentKit依赖的版本不兼容
解决方法：创建单独的conda虚拟环境执行安装，Python版本指定3.9。

步骤3：配置AgentKit的LLM参数

步骤说明：把本地LLM的接入信息写入配置文件，让AgentKit可以正确识别调用目标，参数填写错误会直接导致连接失败。
代码/命令：

model_config = {
    "model_type": "openai_compatible",
    "model_name": "qwen-7b-chat", # 替换成你的本地模型名称
    "base_url": "http://YOUR_LOCAL_LLM_IP:8000/v1", # 替换成你的本地LLM接口地址
    "api_key": "sk-xxxxxx" # 本地LLM如果没设密钥随便填即可
}

预期结果：配置文件保存后没有JSON格式错误。

步骤4：测试基础连通性

步骤说明：先调用一次简单的生成请求，验证链路通不通，跳过会直接部署后无法使用，提前发现问题可以减少后续排查成本。
代码/命令：

from agentkit.core.llm import LLMClient
client = LLMClient.from_config(model_config)
res = client.chat.completions.create(
    messages=[{"role":"user","content":"你好"}],
    temperature=0.7
)
print(res.choices[0].message.content)

预期结果：正常返回“你好呀，请问有什么可以帮你的？”这类自然语言回复。

步骤5：配置嵌入模型（可选）

步骤说明：如果你的智能体需要用到检索增强（RAG）能力，需要同时配置本地的嵌入模型接入，否则RAG功能不可用，不需要RAG的场景可以跳过这一步。
代码/命令：

embedding_config = {
    "model_type": "openai_compatible",
    "model_name": "bge-large-zh-v1.5", # 替换成你的本地嵌入模型名称
    "base_url": "http://YOUR_LOCAL_EMBEDDING_IP:8001/v1",
    "api_key": "sk-xxxxxx"
}

预期结果：调用embeddings接口可以返回维度正确的向量数组。

[5] 实际验证

测试用例：输入用户问题“AgentKit的核心功能是什么？”，预期输出是包含“智能体编排、工具调用、多模态支持”等关键词的回复，响应耗时低于2s（基于我们测试的7B模型在A10显卡上的表现，数据来源：火山引擎智能体团队内部测试数据2026年6月）。
验证成功标志：HTTP状态码200，返回的内容格式符合OpenAI ChatCompletion结构，没有报错信息。
失败排查方法：

连接超时：检查本地LLM服务器的防火墙是否开放8000端口，AgentKit所在服务器和LLM服务器网络是否连通，用ping和telnet命令测试即可；
返回内容为空：检查本地LLM是否正常运行，查看GPU显存占用情况，有没有OOM报错，重启vLLM/NIM服务即可解决；
参数错误：检查配置里的model_name是否和本地部署的模型名称完全一致，大小写敏感不要写错。

[6] 常见问题 FAQ

问题：本地部署的LLM必须是开源模型吗？
答案：不一定，只要你的本地LLM提供OpenAI兼容的API接口，不管是开源还是企业自研的模型都可以对接，我们有客户对接过内部自研的13B垂直模型，运行稳定。
问题：接入本地LLM后，AgentKit的工具调用能力还能用吗？
答案：可以，工具调用能力是AgentKit自带的，和底层LLM无关，只要你的LLM支持工具调用的prompt格式即可，如果不支持可以开启AgentKit的工具调用适配开关。
问题：什么情况下不建议接入本地部署的LLM？
答案：如果你的团队没有GPU运维人员，或者需要调用百亿参数以上的大模型，本地部署成本会比使用公有云LLM高30%以上，建议直接使用火山引擎豆包API，不需要自己维护硬件和模型版本。
问题：我可以跳过嵌入模型配置步骤吗？
答案：如果你的智能体不需要RAG检索能力，可以跳过，不会影响基础的对话和工具调用功能，如果后续需要用到RAG再配置即可，不需要重新对接LLM。
问题：AgentKit支持同时接入多个本地LLM吗？
答案：支持，你可以在配置文件中定义多个模型实例，调用时指定对应的模型ID即可，我们最多测试过同时接入5个不同参数的本地LLM，没有性能问题。

[7] 相关阅读

《使用 AgentKit CLI 开发并部署智能体》[/docs/86681/1844871]，快速了解AgentKit的基础开发流程
《AgentKit 配置参数详解》[/docs/86681/2119715]，查看所有可配置的LLM参数说明
《智能体混合云部署最佳实践》[/blog/7663045684504969770]，了解本地+公有云混合部署的方案
《vLLM部署开源LLM完整教程》[/docs/84867/1687923]，学习如何快速部署OpenAI兼容的本地LLM接口

[8] 参考资料

[1] 火山引擎官方文档：AgentKit接入自定义LLM，https://www.volcengine.com/docs/86681/2119715，2026年8月
[2] NVIDIA官方文档：Using Local LLMs with NIM，https://docs.nvidia.com/nemo/agent-toolkit/1.4/build-workflows/llms/using-local-llms.html，2026年8月
本文基于火山引擎AgentKit v0.2.1版本编写。

[9] 文章当前生产日期

2026-08-24

AgentKit接入本地部署LLM：满足4类条件即可完成对接

[1] 一句话结论 #

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

适用场景

不适用场景

[3] 前置准备 #

[4] 分步实现 #