1. 为什么我用 10 行代码作为 Agent 开发的第一站先说结论Agent 项目不管吹得多花哨落地时都要先去问一句“大模型到底能不能按我的要求稳定返回结果”。而验证这件事10 行代码完全够了。很多人一上来就想整 Agent 框架什么编排、记忆、工具调用配环境都能折腾一整天。我见过不少朋友卡在“框架装好了、Demo 跑不起来、报错看不懂”的阶段最后连“模型到底回了句啥”都没见到。实际上Agent 开发的第一步不是选框架也不是画架构图而是确保你能用一个最简单的请求把大模型接口调通。这一步打通了后面所有上层能力才有地基。这篇文章不是讲高深原理的就是记录我从零开始、用 10 行代码跑通第一次大模型调用的全过程以及在这个过程中踩到的 4 个坑。适合刚入门 Agent 开发、想快速验证 API 连通性的朋友也适合已经写了好几个 Agent 项目但从来没认真整理过“调用链路”的人——你看完可能会发现之前很多莫名其妙的 Bug根子就出在第一条链路上。2. 动手前的关键准备选型与思路拆解2.1 先想清楚“10 行代码”到底要完成什么我给这次任务定了一个非常明确的目标用最小成本让代码从大模型接口拿到一句完整回答。不搞多轮对话不做流式打字机效果不接工具调用甚至不处理超时重试。为什么要这么“抠门”因为目标越小变量越少出问题时越容易定位。你发现没很多人第一次调接口失败根本分不清是“网络不通”“鉴权失败”“模型名写错”还是“参数格式不对”。如果一上来就把请求、解析、历史记录、多轮对话全塞进去报错了你连从哪查起都不知道。所以第一版代码就干一件事发请求、拿结果、打印出来。2.2 接口选型为什么优先选 OpenAI 兼容格式当前主流大模型服务商基本都提供了 OpenAI 兼容接口也就是请求路径和参数格式对齐 OpenAI 的chat/completions规范只是base_url不同。这个设计太关键了它意味着你的调用代码可以只写一套换个环境变量就能切换不同厂商的模型。我当时的选择标准就三条选择标准原因支持 OpenAI 兼容格式代码通用后续切换模型成本低有免费额度或低门槛试用新手期别为调试烧太多钱网络访问相对顺畅避免把时间浪费在“距离问题”上这里多说一句国内也有不少模型服务商提供兼容接口DeepSeek、通义千问、智谱等都行。对于新手我不建议一开始就本地部署开源模型——显卡、环境、显存、量化、推理速度这些问题会瞬间淹没你“只是想跑通一次调用”的目标。等代码链路走通了再考虑要不要本地化部署也不迟。2.3 环境准备一个虚拟环境就够了我不建议直接往全局 Python 环境里装包因为大模型生态的库更新非常快今天装的版本可能明天就deprecated。用虚拟环境隔离是标准操作。python -m venv agent-venv source agent-venv/bin/activate # Windows 下执行 agent-venv\Scripts\activate pip install openai注意这里不需要装requests因为openai库本身已经依赖了requests和httpx装了之后可以直接用。这也是我推荐用官方 SDK 而不是自己用 requests 硬拼请求体的原因——少写代码少踩坑。3. 10 行代码实操从请求到结果解析3.1 完整代码长什么样直接上代码这是我能精简到的最短可运行版本加空行总共 12 行但考虑到import和print核心逻辑就是 10 行左右from openai import OpenAI client OpenAI( api_keysk-你的密钥, base_urlhttps://你的服务商域名/v1 ) response client.chat.completions.create( model模型名称, messages[ {role: system, content: 你是一个测试助手请用一句话回答用户问题。}, {role: user, content: 你好告诉我 11 等于几} ], timeout30 ) print(response.choices[0].message.content)就这么短。运行之后如果一切正常你会看到类似输出11 等于 2。别小看这十几秒的等待和这行输出它意味着你的开发环境、网络链路、API Key、模型路由、参数格式、响应解析整条链路全部是通的。往后你写再复杂的 Agent底层走的都是这条链路。3.2 流式输出让返回值更“像” Agent上面的代码是非流式的也就是说模型生成完一整段回复之后客户端才一次性收到完整内容。但 Agent 项目里我们一般希望“一边生成一边打印”因为用户体验更好响应首字更快。流式版本的代码其实也不复杂核心是加一个streamTrue参数然后遍历responsefrom openai import OpenAI client OpenAI( api_keysk-你的密钥, base_urlhttps://你的服务商域名/v1 ) response client.chat.completions.create( model模型名称, messages[ {role: user, content: 用一句话说明什么是 Agent} ], streamTrue ) for chunk in response: delta chunk.choices[0].delta.content if delta: print(delta, end)跑起来之后文字会一个字一个字蹦出来。这个小细节非常影响 Agent 的“体感”——用户发出指令后如果界面卡几秒突然吐出一大段文字体验会差很多。3.3 非 OpenAI 库方案用 requests 手撸一次也好就算你用openai库跑通了我还是建议你手写一次requests调用。为什么因为openai库帮你隐藏了很多 HTTP 细节一旦出问题你根本不知道底层发了什么。import requests resp requests.post( urlhttps://你的服务商域名/v1/chat/completions, headers{ Authorization: Bearer sk-你的密钥, Content-Type: application/json }, json{ model: 模型名称, messages: [ {role: user, content: 你好回复我一句话} ] }, timeout30 ) data resp.json() print(data[choices][0][message][content])手写一遍的作用是让你意识到所谓大模型调用本质上就是一次普通的 HTTPS POST 请求。请求体是 JSON响应体也是 JSON。你对“调用”这件事的神秘感会瞬间消失后面排查问题也会有底气得多。4. 必踩的 4 个坑与定位过程4.1 坑一模型名不对接口报“Model Not Found”我遇到的第一个问题是model参数写错了。我在代码里填的是deepseek-chat-v3但实际服务商提供的模型名是deepseek-chat。结果接口直接返回Error code: 404 - {error: {message: Model Not Exist, type: invalid_request_error}}这个报错其实是最友好的因为它直接告诉你模型不存在。我当时的第一反应是“我明明看文档了怎么会错”后来重新打开控制台才发现文档首页写的是“模型版本: deepseek-chat”而我凭印象加了个v3后缀。从那以后我每换一个服务商都会先去控制台“模型列表”页核对一遍准确名称绝不复用记忆中的名字。4.2 坑二base_url 拼错导致请求 404第二个坑是base_url的路径问题。我一开始填成了base_urlhttps://api.xxx.com没有带/v1后缀。结果请求发出后直接 404。原因是 OpenAI 兼容接口的路由设计通常要求请求 URL 精确匹配到.../chat/completions如果你把base_url填成根路径SDK 会在后面拼上/chat/completions最终实际请求的 URL 就变成了https://api.xxx.com/chat/completions而服务商根本没有这个路由。正确做法是确认服务商要求的前缀一般就是https://api.xxx.com/v1补全之后就好了。排查这个问题时我抓了一次包看到实际发出的 URL 才恍然大悟。所以也提醒各位如果接口 404别急着怀疑网络先看看最终请求的完整 URL 长什么样。4.3 坑三流式输出时把“空增量”当成内容我在测试流式输出时写了一个遍历循环直接print(chunk)然后发现控制台刷了一大堆 JSON 结构体每个结构体里的choices[0].delta有时候是{content: 你}有时候却是{}空的。我一开始没做空值判断结果就出现间隔性打印空行的问题。后来加了过滤逻辑if chunk.choices[0].delta.content is not None: print(chunk.choices[0].delta.content, end)问题解决。这也算是一个经典坑位——流式响应里不是每个 chunk 都携带内容增量有些 chunk 只传角色信息有些则是结束信号。你需要有一个“只处理有效内容”的意识。4.4 坑四API Key 环境变量没生效各种“Authentication Error”我把 API Key 写进了系统环境变量但在代码里通过os.getenv(API_KEY)读取时打印出来却是None。后来发现是我改了.bashrc之后没有执行source ~/.bashrc当前终端的会话环境压根没有刷新。这个问题非常隐蔽因为“看起来代码没问题、环境变量也配了”但实际运行时读了个空值导致鉴权失败Error code: 401 - {error: {message: Authentication Fails, please check your API Key}}排查建议是在代码里加一行临时调试输出打印os.getenv(API_KEY)[:6]看看能不能读到值。或者直接改成在代码里读取.env文件配合dotenv库会更可控。4.5 踩坑心得汇总坑位表现形式核心原因排查建议模型名错误404 Model Not Found文档信息没核对去控制台复制准确模型名base_url 错误请求 404 或 401缺少 /v1 路由前缀抓包看实际请求 URL流式空增量输出空行/解析报错未过滤无效 chunk判断delta.content是否为空Key 未生效401 鉴权失败环境变量未刷新打印 Key 前缀或改用 .env 文件这些坑单独看都不复杂但串在一起第一次跑通时足以让人怀疑人生。我的经验是遇到报错不要慌先看状态码再抓请求 URL最后检查请求头和请求体。5. 从“调用通”到“Agent 化”接下来还能怎么扩展5.1 先把“一句话对话”升级成“多轮对话”10 行代码让你拿到了模型的第一句回复但 Agent 的对话能力远不止“一问一答”。多轮对话的本质是把历史消息拼进messages数组messages [ {role: system, content: 你是一个简历优化助手。}, {role: user, content: 请帮我把这段经历写得更专业负责公众号运营。}, ]第一次拿到回复后把用户的新问题和助手之前的回答继续追加到messages里再发送请求模型就有了“记忆上下文”。这里有一个容易被忽略的细节messages数组只按顺序传文本真正决定“谁说了什么”的是role字段。system负责设定人设user代表用户输入assistant代表模型历史回答。很多新手写多轮对话时忘了把上一轮模型的回答回传导致模型“失忆”这就是原因。5.2 工具调用让 Agent 真正“做事”的关键一步如果只做大模型问答那还不算 Agent。Agent 和普通聊天的核心区别是它能根据用户意图决定调用哪个外部工具并把工具返回结果整合进回答。比如用户问“现在北京天气怎么样”大模型本身并没有实时数据但通过 Function Calling 机制模型会输出一个结构化的“调用请求”你的代码执行这个请求、把结果塞回上下文模型再基于结果生成最终回答。这里不展开全部细节但可以告诉你的是你刚刚跑通的这 10 行代码就是做这一切的“入口”。后续加一个tools参数、定义几个 JSON Schema、在拿到tool_calls之后路由到具体函数整体思路都是在这条链路上打补丁。5.3 上不上框架我的建议是“先手写一轮再上框架”现在 Agent 框架很多LangChain、AutoGen、CrewAI、以及一些轻量的国产框架各有各的抽象方式。我的建议很明确调用链路都没手撸过的话别直接上框架因为框架层帮你藏住了太多细节一旦出错你连是框架的问题还是接口的问题都分不清排查难度呈指数上升。我自己是先手写了上面 10 行代码然后又手写了流式、多轮、Function Calling 三个小模块最后才去逐个拆解框架源码。这时候再看框架你就能理解它每个抽象是为了解决什么问题。当你发现手写代码已经有不少重复逻辑、状态管理开始混乱时再引入框架你会用得更踏实。6. 部署与术问题跨网络环境调用时怎么排查有个问题是本地跑通了部署到服务器之后却发现调用失败。这种情况多半不是代码问题而是服务器的网络策略限制了对目标 API 域名的访问。排查手段很简单在服务器上直接 curl 一下接口试试curl -X POST https://你的服务商域名/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的密钥 \ -d {model:模型名称,messages:[{role:user,content:你好}],max_tokens:50}如果 curl 能正常返回 JSON说明网络通、鉴权也没问题问题在代码层如果 curl 超时或者报 SSL 错误说明网络策略受限先去检查服务器的防火墙和代理设置。另外一个高频坑是到了某些网络环境里默认使用代理代理影响了对 API 域名的访问。这种情况的表现是本地运行正常、换了个网络就出问题。解决方案很简单在代码里显式指定不走代理import os os.environ[NO_PROXY] api.xxx.com # 替换成实际 API 域名这个细节我是在帮朋友排查时发现的他的代码本地没事一部署到公司服务器就超时折腾了半天最后发现是服务器上配置了全局代理而代理节点访问模型 API 时非常不稳定。这种事遇到一次就有经验了所以我建议你在部署清单里加上一条确认目标服务器的网络策略、代理设置再谈代码级排查。6.1 常见部署期报错速查表现象可能原因解决方向本地正常服务器超时服务器网络策略不通curl 测试连通性看是否需要配代理服务器有代理但请求异常全局代理影响 API 访问对 API 域名设置 NO_PROXY日志显示 SSL 证书错误服务器证书链不全更新 CA 证书或确认目标链路无中间劫持偶发性 503/429触发了限流降低请求频率实现退避重试7. 一些小体会回看整个过程最让我意外的不是代码本身有多困难而是最简单的一步反而是无数人跳过的关键一步。很多新手希望一步到位直接写出一个完美的 Agent结果卡在环境、网络、密钥、模型名这些“低级问题”上。而真正的高手恰恰会花时间把最底层的调用链路打磨得明明白白。10 行代码跑通大模型调用这件事的象征意义大于实际意义。它证明你已经具备了做 Agent 开发的最核心能力能够稳定地从大模型获取结果。接下来要做的就是在这个基础上不断叠加能力——多轮记忆、工具调用、外部知识库、判断与规划一层一层搭上去。如果你正在学 Agent 开发建议你也先给自己立个小目标用最短的代码让模型回你一句话。别贪多先把这一条链路走完然后再考虑下一步。这个目标不需要 GPU不需要框架不需要复杂架构只需要一个 API Key 和十分钟耐心。跑通了以后你会发现Agent 的大门其实已经为你打开一半了。
1. 为什么我用 10 行代码作为 Agent 开发的第一站先说结论Agent 项目不管吹得多花哨落地时都要先去问一句“大模型到底能不能按我的要求稳定返回结果”。而验证这件事10 行代码完全够了。很多人一上来就想整 Agent 框架什么编排、记忆、工具调用配环境都能折腾一整天。我见过不少朋友卡在“框架装好了、Demo 跑不起来、报错看不懂”的阶段最后连“模型到底回了句啥”都没见到。实际上Agent 开发的第一步不是选框架也不是画架构图而是确保你能用一个最简单的请求把大模型接口调通。这一步打通了后面所有上层能力才有地基。这篇文章不是讲高深原理的就是记录我从零开始、用 10 行代码跑通第一次大模型调用的全过程以及在这个过程中踩到的 4 个坑。适合刚入门 Agent 开发、想快速验证 API 连通性的朋友也适合已经写了好几个 Agent 项目但从来没认真整理过“调用链路”的人——你看完可能会发现之前很多莫名其妙的 Bug根子就出在第一条链路上。2. 动手前的关键准备选型与思路拆解2.1 先想清楚“10 行代码”到底要完成什么我给这次任务定了一个非常明确的目标用最小成本让代码从大模型接口拿到一句完整回答。不搞多轮对话不做流式打字机效果不接工具调用甚至不处理超时重试。为什么要这么“抠门”因为目标越小变量越少出问题时越容易定位。你发现没很多人第一次调接口失败根本分不清是“网络不通”“鉴权失败”“模型名写错”还是“参数格式不对”。如果一上来就把请求、解析、历史记录、多轮对话全塞进去报错了你连从哪查起都不知道。所以第一版代码就干一件事发请求、拿结果、打印出来。2.2 接口选型为什么优先选 OpenAI 兼容格式当前主流大模型服务商基本都提供了 OpenAI 兼容接口也就是请求路径和参数格式对齐 OpenAI 的chat/completions规范只是base_url不同。这个设计太关键了它意味着你的调用代码可以只写一套换个环境变量就能切换不同厂商的模型。我当时的选择标准就三条选择标准原因支持 OpenAI 兼容格式代码通用后续切换模型成本低有免费额度或低门槛试用新手期别为调试烧太多钱网络访问相对顺畅避免把时间浪费在“距离问题”上这里多说一句国内也有不少模型服务商提供兼容接口DeepSeek、通义千问、智谱等都行。对于新手我不建议一开始就本地部署开源模型——显卡、环境、显存、量化、推理速度这些问题会瞬间淹没你“只是想跑通一次调用”的目标。等代码链路走通了再考虑要不要本地化部署也不迟。2.3 环境准备一个虚拟环境就够了我不建议直接往全局 Python 环境里装包因为大模型生态的库更新非常快今天装的版本可能明天就deprecated。用虚拟环境隔离是标准操作。python -m venv agent-venv source agent-venv/bin/activate # Windows 下执行 agent-venv\Scripts\activate pip install openai注意这里不需要装requests因为openai库本身已经依赖了requests和httpx装了之后可以直接用。这也是我推荐用官方 SDK 而不是自己用 requests 硬拼请求体的原因——少写代码少踩坑。3. 10 行代码实操从请求到结果解析3.1 完整代码长什么样直接上代码这是我能精简到的最短可运行版本加空行总共 12 行但考虑到import和print核心逻辑就是 10 行左右from openai import OpenAI client OpenAI( api_keysk-你的密钥, base_urlhttps://你的服务商域名/v1 ) response client.chat.completions.create( model模型名称, messages[ {role: system, content: 你是一个测试助手请用一句话回答用户问题。}, {role: user, content: 你好告诉我 11 等于几} ], timeout30 ) print(response.choices[0].message.content)就这么短。运行之后如果一切正常你会看到类似输出11 等于 2。别小看这十几秒的等待和这行输出它意味着你的开发环境、网络链路、API Key、模型路由、参数格式、响应解析整条链路全部是通的。往后你写再复杂的 Agent底层走的都是这条链路。3.2 流式输出让返回值更“像” Agent上面的代码是非流式的也就是说模型生成完一整段回复之后客户端才一次性收到完整内容。但 Agent 项目里我们一般希望“一边生成一边打印”因为用户体验更好响应首字更快。流式版本的代码其实也不复杂核心是加一个streamTrue参数然后遍历responsefrom openai import OpenAI client OpenAI( api_keysk-你的密钥, base_urlhttps://你的服务商域名/v1 ) response client.chat.completions.create( model模型名称, messages[ {role: user, content: 用一句话说明什么是 Agent} ], streamTrue ) for chunk in response: delta chunk.choices[0].delta.content if delta: print(delta, end)跑起来之后文字会一个字一个字蹦出来。这个小细节非常影响 Agent 的“体感”——用户发出指令后如果界面卡几秒突然吐出一大段文字体验会差很多。3.3 非 OpenAI 库方案用 requests 手撸一次也好就算你用openai库跑通了我还是建议你手写一次requests调用。为什么因为openai库帮你隐藏了很多 HTTP 细节一旦出问题你根本不知道底层发了什么。import requests resp requests.post( urlhttps://你的服务商域名/v1/chat/completions, headers{ Authorization: Bearer sk-你的密钥, Content-Type: application/json }, json{ model: 模型名称, messages: [ {role: user, content: 你好回复我一句话} ] }, timeout30 ) data resp.json() print(data[choices][0][message][content])手写一遍的作用是让你意识到所谓大模型调用本质上就是一次普通的 HTTPS POST 请求。请求体是 JSON响应体也是 JSON。你对“调用”这件事的神秘感会瞬间消失后面排查问题也会有底气得多。4. 必踩的 4 个坑与定位过程4.1 坑一模型名不对接口报“Model Not Found”我遇到的第一个问题是model参数写错了。我在代码里填的是deepseek-chat-v3但实际服务商提供的模型名是deepseek-chat。结果接口直接返回Error code: 404 - {error: {message: Model Not Exist, type: invalid_request_error}}这个报错其实是最友好的因为它直接告诉你模型不存在。我当时的第一反应是“我明明看文档了怎么会错”后来重新打开控制台才发现文档首页写的是“模型版本: deepseek-chat”而我凭印象加了个v3后缀。从那以后我每换一个服务商都会先去控制台“模型列表”页核对一遍准确名称绝不复用记忆中的名字。4.2 坑二base_url 拼错导致请求 404第二个坑是base_url的路径问题。我一开始填成了base_urlhttps://api.xxx.com没有带/v1后缀。结果请求发出后直接 404。原因是 OpenAI 兼容接口的路由设计通常要求请求 URL 精确匹配到.../chat/completions如果你把base_url填成根路径SDK 会在后面拼上/chat/completions最终实际请求的 URL 就变成了https://api.xxx.com/chat/completions而服务商根本没有这个路由。正确做法是确认服务商要求的前缀一般就是https://api.xxx.com/v1补全之后就好了。排查这个问题时我抓了一次包看到实际发出的 URL 才恍然大悟。所以也提醒各位如果接口 404别急着怀疑网络先看看最终请求的完整 URL 长什么样。4.3 坑三流式输出时把“空增量”当成内容我在测试流式输出时写了一个遍历循环直接print(chunk)然后发现控制台刷了一大堆 JSON 结构体每个结构体里的choices[0].delta有时候是{content: 你}有时候却是{}空的。我一开始没做空值判断结果就出现间隔性打印空行的问题。后来加了过滤逻辑if chunk.choices[0].delta.content is not None: print(chunk.choices[0].delta.content, end)问题解决。这也算是一个经典坑位——流式响应里不是每个 chunk 都携带内容增量有些 chunk 只传角色信息有些则是结束信号。你需要有一个“只处理有效内容”的意识。4.4 坑四API Key 环境变量没生效各种“Authentication Error”我把 API Key 写进了系统环境变量但在代码里通过os.getenv(API_KEY)读取时打印出来却是None。后来发现是我改了.bashrc之后没有执行source ~/.bashrc当前终端的会话环境压根没有刷新。这个问题非常隐蔽因为“看起来代码没问题、环境变量也配了”但实际运行时读了个空值导致鉴权失败Error code: 401 - {error: {message: Authentication Fails, please check your API Key}}排查建议是在代码里加一行临时调试输出打印os.getenv(API_KEY)[:6]看看能不能读到值。或者直接改成在代码里读取.env文件配合dotenv库会更可控。4.5 踩坑心得汇总坑位表现形式核心原因排查建议模型名错误404 Model Not Found文档信息没核对去控制台复制准确模型名base_url 错误请求 404 或 401缺少 /v1 路由前缀抓包看实际请求 URL流式空增量输出空行/解析报错未过滤无效 chunk判断delta.content是否为空Key 未生效401 鉴权失败环境变量未刷新打印 Key 前缀或改用 .env 文件这些坑单独看都不复杂但串在一起第一次跑通时足以让人怀疑人生。我的经验是遇到报错不要慌先看状态码再抓请求 URL最后检查请求头和请求体。5. 从“调用通”到“Agent 化”接下来还能怎么扩展5.1 先把“一句话对话”升级成“多轮对话”10 行代码让你拿到了模型的第一句回复但 Agent 的对话能力远不止“一问一答”。多轮对话的本质是把历史消息拼进messages数组messages [ {role: system, content: 你是一个简历优化助手。}, {role: user, content: 请帮我把这段经历写得更专业负责公众号运营。}, ]第一次拿到回复后把用户的新问题和助手之前的回答继续追加到messages里再发送请求模型就有了“记忆上下文”。这里有一个容易被忽略的细节messages数组只按顺序传文本真正决定“谁说了什么”的是role字段。system负责设定人设user代表用户输入assistant代表模型历史回答。很多新手写多轮对话时忘了把上一轮模型的回答回传导致模型“失忆”这就是原因。5.2 工具调用让 Agent 真正“做事”的关键一步如果只做大模型问答那还不算 Agent。Agent 和普通聊天的核心区别是它能根据用户意图决定调用哪个外部工具并把工具返回结果整合进回答。比如用户问“现在北京天气怎么样”大模型本身并没有实时数据但通过 Function Calling 机制模型会输出一个结构化的“调用请求”你的代码执行这个请求、把结果塞回上下文模型再基于结果生成最终回答。这里不展开全部细节但可以告诉你的是你刚刚跑通的这 10 行代码就是做这一切的“入口”。后续加一个tools参数、定义几个 JSON Schema、在拿到tool_calls之后路由到具体函数整体思路都是在这条链路上打补丁。5.3 上不上框架我的建议是“先手写一轮再上框架”现在 Agent 框架很多LangChain、AutoGen、CrewAI、以及一些轻量的国产框架各有各的抽象方式。我的建议很明确调用链路都没手撸过的话别直接上框架因为框架层帮你藏住了太多细节一旦出错你连是框架的问题还是接口的问题都分不清排查难度呈指数上升。我自己是先手写了上面 10 行代码然后又手写了流式、多轮、Function Calling 三个小模块最后才去逐个拆解框架源码。这时候再看框架你就能理解它每个抽象是为了解决什么问题。当你发现手写代码已经有不少重复逻辑、状态管理开始混乱时再引入框架你会用得更踏实。6. 部署与术问题跨网络环境调用时怎么排查有个问题是本地跑通了部署到服务器之后却发现调用失败。这种情况多半不是代码问题而是服务器的网络策略限制了对目标 API 域名的访问。排查手段很简单在服务器上直接 curl 一下接口试试curl -X POST https://你的服务商域名/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的密钥 \ -d {model:模型名称,messages:[{role:user,content:你好}],max_tokens:50}如果 curl 能正常返回 JSON说明网络通、鉴权也没问题问题在代码层如果 curl 超时或者报 SSL 错误说明网络策略受限先去检查服务器的防火墙和代理设置。另外一个高频坑是到了某些网络环境里默认使用代理代理影响了对 API 域名的访问。这种情况的表现是本地运行正常、换了个网络就出问题。解决方案很简单在代码里显式指定不走代理import os os.environ[NO_PROXY] api.xxx.com # 替换成实际 API 域名这个细节我是在帮朋友排查时发现的他的代码本地没事一部署到公司服务器就超时折腾了半天最后发现是服务器上配置了全局代理而代理节点访问模型 API 时非常不稳定。这种事遇到一次就有经验了所以我建议你在部署清单里加上一条确认目标服务器的网络策略、代理设置再谈代码级排查。6.1 常见部署期报错速查表现象可能原因解决方向本地正常服务器超时服务器网络策略不通curl 测试连通性看是否需要配代理服务器有代理但请求异常全局代理影响 API 访问对 API 域名设置 NO_PROXY日志显示 SSL 证书错误服务器证书链不全更新 CA 证书或确认目标链路无中间劫持偶发性 503/429触发了限流降低请求频率实现退避重试7. 一些小体会回看整个过程最让我意外的不是代码本身有多困难而是最简单的一步反而是无数人跳过的关键一步。很多新手希望一步到位直接写出一个完美的 Agent结果卡在环境、网络、密钥、模型名这些“低级问题”上。而真正的高手恰恰会花时间把最底层的调用链路打磨得明明白白。10 行代码跑通大模型调用这件事的象征意义大于实际意义。它证明你已经具备了做 Agent 开发的最核心能力能够稳定地从大模型获取结果。接下来要做的就是在这个基础上不断叠加能力——多轮记忆、工具调用、外部知识库、判断与规划一层一层搭上去。如果你正在学 Agent 开发建议你也先给自己立个小目标用最短的代码让模型回你一句话。别贪多先把这一条链路走完然后再考虑下一步。这个目标不需要 GPU不需要框架不需要复杂架构只需要一个 API Key 和十分钟耐心。跑通了以后你会发现Agent 的大门其实已经为你打开一半了。
