大模型选型与Agent开发实战：从API接入到微调部署的避坑指南

1. 大模型选型的底层逻辑：为什么不能只看跑分

这两年我经手过不少大模型落地的项目，从最开始的“哪个榜单第一就用哪个”，到后来被现实反复教育，慢慢摸清楚一件事：选模型本质上是在选一套约束条件下的最优解，而不是选一个绝对意义上的最强者。GPT-5、GPT-6、Claude Opus 5.5，还有国内一批主流模型，它们之间的差异远不止参数规模和跑分高低，更多体现在上下文窗口、工具调用稳定性、API 计费结构、内容合规边界、以及和你现有技术栈的契合度上。

先说说为什么“只看跑分”这件事特别容易翻车。公开榜单上的分数，大多是在标准化数据集上跑出来的，题目类型固定、提示词经过精心设计、评测环境干净。但真实业务里，你的输入是脏的，用户会打错字、会一次塞进来三万字的需求文档、会让你在对话中途切换任务。我见过太多团队拿着榜单第一的模型上线，结果发现它在多轮工具调用时频繁丢上下文，最后不得不回退到榜单第三第四的模型。所以选型的第一步，是把你的真实场景拆成几个可量化的维度，而不是盯着一个综合分。

我一般会把评估维度拆成这么几块：推理深度、上下文长度、工具调用（Agent）能力、响应延迟、单位成本、以及合规可控性。这六项里，前两项决定“能不能做对”，中间两项决定“能不能用起来”，后两项决定“能不能长期用得起、用得安心”。GPT-5 系列在推理深度上确实强，尤其在需要多步逻辑链的任务里表现稳定；GPT-6 在长上下文和工具编排上做了明显加强，适合做 Agent 中枢；Claude Opus 5.5 的长文本理解和代码能力是它的招牌，很多做代码助手和文档分析的团队会优先考虑它。国内模型则在中文语境、本地化部署、以及 API 成本上有天然优势，尤其是需要私有化部署或者对数据出境有要求的场景。

这里有个很关键的认知：模型能力是动态的，但你的架构应该是相对稳定的。我现在的做法是，在业务层和模型层之间加一层抽象，把“调用哪个模型”这件事做成可配置的。这样当新模型发布、或者某个模型涨价、或者某个模型突然不可用时，我只需要改配置，不用重写业务代码。这层抽象听起来简单，但真正做起来要考虑的东西不少，比如不同模型的 API 格式不一样、返回结构不一样、错误码不一样、流式输出的分片方式也不一样。后面我会专门讲怎么设计这层适配。

还有一个容易被忽略的点是模型的“性格”。同样是写代码，有的模型倾向于给你完整可运行的代码块，有的喜欢先解释再给代码，有的会在你没要求的情况下加一堆注释。这些差异在单次调用里不明显，但在 Agent 场景下会被放大——因为 Agent 会基于模型的输出去决定下一步动作，模型输出风格的微小差异，可能导致整个任务链走向完全不同的方向。所以我在做 Agent 项目时，会专门花时间测试模型在“指令遵循”和“格式稳定性”上的表现，而不是只看它能不能答对题。

2. 主流模型能力横向拆解：GPT、Claude 与国产阵营的真实差异

2.1 GPT 系列：从 GPT-5 到 GPT-6 的演进重点

GPT-5 到 GPT-6 这一代，我感受到的最大变化不是“更聪明了”，而是更稳了。GPT-5 在复杂推理上已经很强，但它在长对话里偶尔会“忘记”前面设定的约束，比如你让它始终用 JSON 输出，聊到第十轮它可能就给你返回一段自然语言。GPT-6 在这方面改善明显，指令遵循的持久性更好，尤其是在 Agent 多轮循环里，格式漂移的情况少了很多。

另一个变化是工具调用的编排能力。GPT-6 对并行工具调用的支持更成熟，你可以一次性让它调用多个函数，然后它会把结果整合起来再推理。这在做数据查询类 Agent 时特别有用——比如一个任务需要同时查天气、查库存、查物流，GPT-6 可以并行发起，而不是串行等待。实测下来，并行调用能把整体延迟压下来不少，但前提是你的工具接口要足够稳定，因为并行意味着任何一个环节出错都会影响整体。

不过 GPT 系列也有它的“脾气”。它的 API 对提示词长度比较敏感，超过一定 token 数之后，响应质量会下降，而且计费是按输入输出分别算的，长上下文场景下成本上升很快。我一般会在调用前做一层提示词压缩，把不必要的历史对话裁掉，只保留关键上下文。这个压缩逻辑我后面会给一个具体的实现思路。

2.2 Claude Opus 5.5：长文本与代码场景的优等生

Claude Opus 5.5 我用得最多的场景是代码审查和长文档分析。它的上下文窗口大，而且在大窗口下的“注意力”保持得不错，不像有些模型窗口一大就开始丢中间的内容。我试过把一份两百页的技术文档丢给它，让它找出其中前后矛盾的地方，它确实能定位到相隔很远的两个章节之间的冲突，这个能力在合同审查、技术方案评审里很实用。

代码方面，Claude Opus 5.5 对代码结构的理解比较到位，尤其是当你给它一个不完整的代码片段，让它补全或者找 bug 时，它往往能顺着调用链往上往下推。但它的 API 响应速度相对慢一些，如果你做的是实时对话类产品，可能需要考虑用更轻量的模型做前置，把复杂任务路由给 Claude。

还有一个实际使用中的细节：Claude 的 API 对系统提示词（system prompt）的处理方式和 GPT 不太一样。它更“听话”，但如果你给的约束太多太杂，它反而会变得保守，输出变得很短。我的经验是，给 Claude 的提示词要分层，把硬性约束和软性建议分开写，硬性约束放前面，软性建议放后面，这样它的表现会更符合预期。

2.3 国产主流模型：中文场景与私有化部署的务实选择

国内这批主流模型，我在中文任务上用得比较多。它们在中文语义理解、成语俗语处理、以及本地化知识上有天然优势。比如做客服机器人，国产模型对“亲”“麻烦您”“稍等哈”这类口语化表达的处理更自然，而 GPT 系列有时候会显得过于正式。

更重要的是私有化部署这条路。很多企业客户对数据出境有硬性要求，这时候国产模型就是唯一选择。私有化部署要考虑的东西比调 API 多得多：显存够不够、推理框架选哪个、并发怎么扛、模型量化到什么程度。我一般会先做一轮压测，确定单卡能扛多少并发，再决定是单机部署还是集群部署。量化方面，INT8 量化通常能把显存占用降一半左右，但精度损失要看具体任务，做分类任务问题不大，做生成任务就要谨慎。

国产模型的 API 生态这两年也成熟了不少，很多都兼容 OpenAI 的接口格式，这意味着你之前为 GPT 写的代码，改个 base_url 和 api_key 就能跑。但要注意，兼容不等于完全一致，有些模型对某些参数不支持，或者返回结构有细微差别，接入时还是要做一轮适配测试。

2.4 一张表看清主流模型的关键差异

这张表不是让你照着选，而是让你看清楚每个模型的“偏科”在哪里。实际选型时，我会把业务需求按优先级排序，然后看哪个模型在最关键的维度上不拖后腿。

3. API 接入实操：从密钥管理到错误排查的完整链路

3.1 API Key 的安全管理：别把密钥写进代码里

我见过太多项目把 API Key 直接硬编码在代码里，然后一不小心提交到了公开仓库。这种事一旦发生，轻则被人盗刷额度，重则密钥泄露导致账号被封。正确的做法是用环境变量或者密钥管理服务。本地开发用.env文件，但记得把.env加进.gitignore；生产环境用云厂商的密钥管理服务，或者至少用容器编排平台的 Secret 机制。

# .env 文件示例，不要提交到仓库 OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxx DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxx

读取的时候用代码加载，不要写死：

import os from dotenv import load_dotenv load_dotenv() api_key = os.getenv("OPENAI_API_KEY") if not api_key: raise ValueError("API Key 未配置，请检查环境变量")

这里有个细节：不同厂商的 Key 前缀不一样，比如 OpenAI 的通常是sk-开头，Anthropic 的是sk-ant-开头。如果你在日志里看到sk-svcac****这种被截断的 Key，说明某处打印了密钥，赶紧去查日志脱敏逻辑。我一般会在日志中间件里加一层正则，把所有sk-开头的字符串替换成sk-***，避免密钥意外泄露。

3.2 401 与 400 错误：最常见的两类报错怎么解

unexpected status 401 unauthorized: incorrect api key provided这个错误，我敢说每个接过 API 的人都遇到过。它的原因就那么几个：Key 写错了、Key 过期了、Key 对应的账号欠费了、或者你把 Key 用在了错误的 base_url 上。排查顺序我一般是：先确认 Key 有没有多余空格（复制粘贴时特别容易带上），再确认 base_url 是不是对应厂商的，最后去控制台看账号状态。

# 一个简单的连通性测试脚本 import requests def test_api(base_url, api_key, model): headers = { "Authorization": f"Bearer {api_key}", "Content-Type": "application/json" } payload = { "model": model, "messages": [{"role": "user", "content": "ping"}], "max_tokens": 5 } resp = requests.post(f"{base_url}/chat/completions", headers=headers, json=payload, timeout=30) print(resp.status_code, resp.text[:200]) test_api("https://api.openai.com/v1", os.getenv("OPENAI_API_KEY"), "gpt-4o")

api error: 400 this model's maximum context length is 1048576 tokens这个错误则是上下文超限。注意这里的数字是 1048576，也就是 1M token，说明你用的模型支持超大窗口，但你的输入还是超了。解决办法有两个：一是做提示词压缩，把历史对话摘要化；二是做分块处理，把长文档切成多段分别处理再合并结果。我一般优先用摘要压缩，因为分块会丢失跨块的上下文关联。

3.3 多模型适配层：一套代码调所有模型

前面说过，我习惯在业务和模型之间加一层适配。这层的核心是把不同厂商的 API 差异屏蔽掉，对外暴露统一的接口。下面是一个简化版的适配层设计：

from abc import ABC, abstractmethod class LLMProvider(ABC): @abstractmethod def chat(self, messages, **kwargs): pass class OpenAIProvider(LLMProvider): def __init__(self, api_key, base_url="https://api.openai.com/v1"): self.api_key = api_key self.base_url = base_url def chat(self, messages, **kwargs): # 调用 OpenAI 兼容接口 # 返回统一格式 {"content": "...", "usage": {...}} pass class AnthropicProvider(LLMProvider): def __init__(self, api_key): self.api_key = api_key def chat(self, messages, **kwargs): # 调用 Anthropic 接口，转换消息格式 # 返回统一格式 pass class ProviderFactory: @staticmethod def create(provider_name, **config): if provider_name == "openai": return OpenAIProvider(**config) elif provider_name == "anthropic": return AnthropicProvider(**config) elif provider_name == "deepseek": return OpenAIProvider(**config) # 兼容 OpenAI 格式 else: raise ValueError(f"不支持的厂商: {provider_name}")

这层适配的价值在于，当你想从 GPT 切到 Claude，或者从 Claude 切到国产模型时，业务代码一行不用改。我实际项目里还会在这层加上重试、降级、限流、计费统计这些横切关注点。重试策略一般是：网络错误重试 3 次，指数退避；429 限流错误等待后重试；401/400 这类客户端错误不重试，直接抛给上层。

4. Agent 开发实战：工具调用与任务编排的关键细节

4.1 Agent 的本质：让模型学会“用工具”

Agent 这个词这两年特别火，但剥开外壳看，它的核心就是让模型在推理过程中调用外部工具，并根据工具返回的结果继续推理。一个最简 Agent 循环是这样的：模型收到任务 → 判断需要调用哪个工具 → 输出工具调用请求 → 系统执行工具 → 把结果喂回模型 → 模型继续推理或给出最终答案。这个循环会一直持续，直到模型认为任务完成。

听起来简单，但实际做起来坑很多。第一个坑是工具描述的清晰度。模型是根据你给的工具描述来决定调不调的，如果描述写得含糊，模型要么不调，要么调错。我写工具描述的原则是：说清楚这个工具做什么、什么时候用、参数是什么格式、返回什么结构。比如一个查天气的工具，描述不能只写“查天气”，要写“根据城市名查询当前天气，输入城市中文名，返回温度和天气状况”。

tools = [ { "type": "function", "function": { "name": "get_weather", "description": "根据城市名称查询当前天气情况。当用户询问某个城市的天气时使用此工具。", "parameters": { "type": "object", "properties": { "city": { "type": "string", "description": "城市中文名称，例如：北京、上海" } }, "required": ["city"] } } } ]

第二个坑是工具调用的循环控制。模型有时候会陷入死循环，反复调用同一个工具。我一般会设置最大循环次数，比如 10 次，超过就强制中断并返回当前结果。同时会在提示词里加一句“如果已经获取到足够信息，请直接给出最终答案，不要重复调用工具”。

4.2 多模型路由：什么任务交给什么模型

在 Agent 架构里，我不建议所有任务都用同一个模型。我的做法是做一层路由：简单任务（比如意图识别、参数提取）用轻量模型，复杂任务（比如多步推理、代码生成）用强模型。这样既能控制成本，又能保证关键环节的质量。

路由的判断逻辑可以基于任务类型，也可以基于输入长度。比如输入超过 5000 token 的文档分析任务，路由给 Claude；需要并行工具调用的任务，路由给 GPT-6；中文客服对话，路由给国产模型。这层路由我一般用规则引擎实现，简单直接，比用模型来判断更可控。

def route_model(task_type, input_length, requires_tools): if task_type == "code_review": return "claude-opus-5.5" elif task_type == "customer_service" and input_length < 2000: return "domestic-model-a" elif requires_tools and input_length > 5000: return "gpt-6" else: return "gpt-5"

4.3 Agent 执行中断的排查思路

agent execution terminated due to error这个报错信息很笼统，它可能是工具调用失败、可能是模型返回格式不对、也可能是超时。我的排查顺序是：先看日志里最后一次成功的工具调用是什么，再看模型最后一次返回的原始内容，最后看是不是触发了循环上限或者超时限制。

我一般会在 Agent 的每一步都打详细日志：模型输入、模型输出、工具调用请求、工具返回结果、耗时。这样出问题时能快速定位到是哪一步断的。日志里要注意脱敏，把 API Key、用户隐私数据都过滤掉。

还有一个常见问题是模型返回的 JSON 格式不合法。有些模型在工具调用时，参数 JSON 会多一个逗号或者少一个引号，导致解析失败。我的做法是在解析前先做一轮清洗，用正则把常见的格式问题修掉，解析失败时把原始内容记下来，方便后续分析。

5. 大模型微调与部署：从数据准备到量化上线

5.1 微调前先问自己：真的需要微调吗

微调不是万能药。我见过不少团队一上来就想微调，结果发现效果还不如好好写提示词。微调适合的场景是：你有大量领域特定数据、提示词工程已经做到极限、且任务对格式或风格有严格要求。如果只是想让模型回答得更准，优先考虑 RAG（检索增强生成），把知识放在外部检索里，而不是塞进模型参数。

微调的数据准备是个体力活。我一般会准备至少几百条高质量样本，格式是“输入-输出”对。数据质量比数量重要，一百条干净的数据往往比一千条脏数据效果好。数据要覆盖你的真实场景，包括边界情况和容易出错的案例。

5.2 微调实战：参数选择与训练监控

微调时最关键的是学习率和训练轮数。学习率太大，模型会“忘掉”原有能力；学习率太小，又学不进去。我一般从 1e-5 到 5e-5 之间试，先跑一小轮看 loss 曲线。如果 loss 下降很快然后反弹，说明学习率太大；如果 loss 几乎不动，说明学习率太小。

训练轮数一般 3 到 5 轮就够了，再多容易过拟合。我会在训练过程中定期用验证集评估，看模型在没见过的数据上表现如何。如果验证集 loss 开始上升，就说明过拟合了，该停了。

# 微调参数示例（以常见框架为例） training_args = { "learning_rate": 2e-5, "num_train_epochs": 3, "per_device_train_batch_size": 4, "gradient_accumulation_steps": 4, "warmup_ratio": 0.1, "logging_steps": 10, "save_steps": 100, "evaluation_strategy": "steps", "eval_steps": 50 }

5.3 部署与量化：显存不够怎么办

私有化部署最现实的问题就是显存。一个 70B 参数的模型，FP16 精度下大概需要 140GB 显存，普通单卡根本放不下。这时候就要用量化。INT8 量化能把显存降到 70GB 左右，INT4 量化能降到 35GB 左右。量化会损失一些精度，但实测下来，做分类和抽取任务损失很小，做生成任务要具体看。

部署框架我一般用 vLLM 或者 TGI，它们对并发和吞吐做了优化。部署时要压测，确定单卡能扛多少并发。压测方法是逐步增加并发数，观察响应时间和错误率，找到拐点。超过拐点后，响应时间会急剧上升，这时候就该加卡或者做限流了。

6. 常见问题速查与避坑经验

6.1 错误码速查表

6.2 我踩过的几个坑

第一个坑是把 Key 写进了前端代码。早期做 demo 时图省事，直接把 Key 放在前端调用，结果被人抓包盗刷。后来所有调用都走后端代理，前端永远不接触 Key。

第二个坑是没做超时控制。有一次模型响应特别慢，整个请求卡了五分钟，用户体验极差。后来所有 API 调用都加了超时，一般设 30 到 60 秒，超时就降级到备用模型或者返回缓存结果。

第三个坑是忽略 token 计费。长上下文场景下，输入 token 消耗很快，一个月下来账单吓人。后来我加了 token 统计，每次调用都记录输入输出 token 数，月底能清楚看到钱花在哪了。

6.3 几个实用小技巧

提示词压缩方面，我一般会把历史对话做摘要，只保留最近几轮原文和更早轮次的摘要。这样既能保持上下文连贯，又能控制 token 数。摘要用轻量模型做就行，成本很低。

多模型降级方面，我会给每个任务配一个主模型和一个备用模型。主模型超时或者报错时，自动切到备用模型。备用模型一般选响应快、成本低的，保证基本可用。

日志脱敏方面，我写了一个正则中间件，把所有sk-开头的字符串、手机号、邮箱都替换掉。这个中间件在日志输出前执行，确保落盘的日志是干净的。

最后分享一个我个人的习惯：每次接入新模型，我都会先跑一轮“冒烟测试”，用一组固定的提示词测试它的基本能力、格式稳定性、工具调用、错误处理。这组测试用例我攒了两年，覆盖了各种边界情况，新模型一跑就知道能不能用。这个习惯帮我省了很多上线后才发现问题的时间。