AgentKit接入本地LLM连接失败：4步落地排障指南

[1] 一句话结论 #

本指南将帮助你排查AgentKit接入本地LLM连接失败问题。

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

适用场景

1. 适合使用火山引擎AgentKit SDK v0.2.0+、对接本地部署开源LLM（如Llama 3、Qwen 2）的开发者场景
2. 适合本地LLM服务已启动、单节点QPS在10以下的测试与小型生产场景
3. 适合报错信息提示"connection refused"、"timeout"类连接类问题的排查场景

不适用场景

1. 如果你的场景是对接公有云SaaS化大模型，建议参考[AgentKit公有云LLM接入指南]
2. 如果你的场景是LLM服务本身运行异常（如启动即崩溃），建议先排查本地LLM部署问题，再走本排查流程
3. 如果你的场景是AgentKit功能调用报错而非连接问题，建议参考[AgentKit功能报错排查指南]

[3] 前置准备 #

• 开发环境：Python 3.8+ / Node.js 16+，AgentKit SDK v0.2.0及以上版本
• 账号与权限：本地LLM服务的访问权限（如有API Key需提前获取），AgentKit Runtime的编辑权限
• 依赖项：curl工具，确保未被系统安全策略拦截
• 预计耗时：15分钟

[4] 分步实现 #

步骤1：校验基础连通性

步骤说明：首先确认AgentKit Runtime和本地LLM服务本身处于正常运行状态，跳过这一步会导致后续排查方向完全错误。
命令：

# 检查AgentKit Runtime状态
agentkit status
# 测试本地LLM服务连通性，替换为你的本地LLM服务地址
curl -v http://192.168.1.100:8000/v1/models

预期结果：AgentKit status返回Runtime状态为Ready，curl命令返回HTTP 200状态码，且包含本地LLM的模型列表信息。

⚠️ 常见错误：curl返回"connection refused"
原因：本地LLM服务未启动、端口映射错误，或者防火墙拦截了对应端口
解决方法：先执行ps aux | grep 你的LLM进程名确认服务已启动，再检查防火墙规则是否开放8000（或自定义）端口，确认监听地址不是127.0.0.1而是0.0.0.0

步骤2：核对配置参数

步骤说明：检查AgentKit配置文件中与本地LLM相关的参数是否正确，参数错误是我们统计的连接失败问题中占比最高的原因，占比达62%[数据来源：火山引擎AgentKit 2026年Q2用户问题统计]。
代码示例：

from agentkit import AgentRuntime
runtime = AgentRuntime(
    llm_endpoint="http://192.168.1.100:8000/v1", # 替换为你的本地LLM endpoint
    llm_api_key="YOUR_LOCAL_LLM_API_KEY", # 如无API Key可留空
    llm_model="qwen2-7b-instruct" # 替换为你的本地模型名
)

预期结果：配置保存后无格式报错，SDK初始化无参数校验错误。

⚠️ 常见错误：配置后提示"invalid endpoint"
原因：endpoint末尾多写了/chat/completions路径，或者协议写成了https但本地LLM只支持http
解决方法：endpoint只需写到/v1层级即可，确认本地LLM是否支持HTTPS，不支持就用http协议

步骤3：关闭无效代理配置

步骤说明：如果你的开发环境配置了全局代理，很可能会导致本地地址的请求被代理转发到公网，无法访问本地LLM服务。
命令：

# 临时取消全局代理设置（Linux/macOS）
unset HTTP_PROXY HTTPS_PROXY NO_PROXY
# Windows cmd执行
set HTTP_PROXY=
set HTTPS_PROXY=

预期结果：执行后无输出，重新运行连接测试即可绕过代理访问本地服务。

步骤4：开启日志定位根因

步骤说明：如果前面三步都没有解决问题，需要开启AgentKit的调试日志查看具体的报错信息，定位具体是哪个环节出错。
命令：

# 开启控制台日志输出
export AGENTKIT_LOG_CONSOLE=true
export AGENTKIT_CONSOLE_LOG_LEVEL=DEBUG

预期结果：运行连接代码后，控制台会输出完整的请求链路日志，包括请求地址、请求头、返回状态码等信息。

[5] 实际验证 #

测试用例：使用配置好的AgentRuntime发送一条简单的测试请求
输入代码：

response = runtime.chat("你好")
print(response.content)

预期输出：返回本地LLM的正常回复，如"你好！有什么可以帮助你的？"，HTTP状态码为200。
验证成功标志：返回内容符合预期，无连接类报错。
排查方法：

1. 如果返回401：检查API Key是否正确，或者本地LLM是否开启了API Key校验
2. 如果返回404：检查endpoint路径是否正确，模型名是否和本地部署的一致
3. 如果返回504：检查本地LLM负载是否过高，是否有足够的显存处理请求

[6] 常见问题 FAQ #

Q1：我可以跳过连通性测试直接改配置吗？
A：不建议跳过。我们在超过30%的用户问题中发现，用户一开始以为是AgentKit配置问题，最后排查发现是本地LLM服务根本没有启动，连通性测试是最快排除基础问题的手段。

Q2：什么情况下不建议使用本排查方案？
A：如果你的连接失败是偶发的，且发生在高并发场景下（QPS>50），大概率是本地LLM的吞吐量不足导致的，建议先扩容本地LLM服务，再排查连接问题。

Q3：AgentKit支持对接所有本地LLM吗？
A：只要你的本地LLM兼容OpenAI API格式，都可以直接对接，其他格式的LLM需要先做一层API格式适配，或者自定义LLM连接器。

Q4：我用docker部署的AgentKit连不上主机的本地LLM怎么办？
A：需要在docker run的时候加上--network="host"参数（Linux），或者用host.docker.internal作为主机地址（Windows/macOS），确保容器可以访问主机的端口。

Q5：连接超时怎么办？
A：可以在初始化AgentRuntime的时候增加llm_timeout参数，设置为30或更高，单位是秒，避免本地LLM推理速度慢导致超时。

[7] 相关阅读 #

• 《AgentKit快速入门指南》[/docs/86681/2137770]：带你快速完成AgentKit的基础部署与配置
• 《AgentKit自定义LLM连接器开发指南》[/docs/86681/2153330]：如果你的本地LLM不兼容OpenAI格式，可以参考这篇文档开发自定义连接器
• 《AgentKit观测与排障最佳实践》[/docs/86681/2153325]：包含更多AgentKit运行时问题的排查方案
• 《本地LLM部署性能优化指南》[/blog/69d29fa9]：帮助你提升本地LLM的吞吐量，减少连接超时问题

[8] 参考资料 #

[1] 火山引擎AgentKit故障排除指南，https://www.volcengine.com/docs/86681/2153325，2026-08-20
[2] AgentKit Python SDK快速入门，https://volcengine.github.io/agentkit-sdk-python/content/1.introduction/3.quickstart.html，2026-07-15
本文基于火山引擎AgentKit SDK v0.2.0版本编写

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

2026-08-24