用你的微调本地模型替换 OpenAI Agents SDK 中的 OpenAI

更新于 2026-05-10——反映 OpenAI Agents SDK v0.17.0(2026 年 5 月 7 日),它把默认 RealtimeAgent 模型升级为 gpt-realtime-2。在生产中固定到特定 SDK 版本,而非追踪移动的默认值——下方的替换模式无论如何都不变。

OpenAI Agents SDK 是 2026 年发布的最干净的智能体框架之一。它是 Swarm 的生产级继任者,具备一流的工具调用、智能体之间的交接、结构化输出以及为整个生态设定标准的追踪系统。尽管盒子上的名字如此,它并不只服务于 OpenAI。SDK 接受任何兼容 OpenAI 的 HTTP 端点作为支撑模型,这意味着开发体验在你换出模型时与你同行。

这个细节是本指南的全部要点。你可以基于该 SDK 构建智能体,先针对 OpenAI 托管模型做原型,然后让同一份代码指向在 Ollama 上本地运行的微调 7B 模型。智能体代码不变。追踪不变。账单变了——大致一个数量级或更多,取决于流量。

这为何重要

智能体应用消耗 token 的方式与聊天机器人不同。一次典型聊天轮次是一两次模型调用。一次典型智能体任务是 5 到 30 次模型调用,因为智能体思考、挑工具、读工具输出、决定下一步,如此等等。token 账单随循环扩展,而非随用户可见轮次扩展。

由此产生的经济形态不寻常。运行在基线云 API 上、月活 1K 的智能体产品通常每月推理只付约 120 美元。创始人看到这个数字会假设单位经济模型没问题。实际上并非如此。在 40K MAU 时,同一产品每月支付 3,000 美元以上,考虑到重试、更长上下文与复杂流程,通常更接近 6,000 美元。成本线随用户大致线性上升,而每用户营收增长远不及它。

微调本地模型修正了曲线。成本是固定的:后端路径上一台 GPU 实例,设备端路径上一次性模型下载。再增加 10 万用户,账单仍然一样。

设置:一个客户支持分诊智能体

我们将构建一个分诊智能体,它对入站支持请求分类、查询客户、必要时创建工单,并对高严重度请求升级到人工。它有三个工具与清晰范围,这使其成为微调的良好候选。

新建一个 Python 项目并安装 OpenAI Agents SDK。

pip install openai-agents

下面是该智能体。它有意保持简短——大约 25 行有意义的代码——因为 SDK 设计良好。

from agents import Agent, Runner, function_tool
from pydantic import BaseModel

class TriageDecision(BaseModel):
    category: str
    severity: int
    ticket_id: str | None = None
    escalated: bool = False

@function_tool
def lookup_customer(email: str) -> dict:
    """Look up customer details by email address."""
    return crm.get_customer(email)

@function_tool
def create_ticket(customer_id: str, summary: str, severity: int) -> str:
    """Create a support ticket. Returns the ticket ID."""
    return tickets.create(customer_id, summary, severity)

@function_tool
def escalate(customer_id: str, reason: str) -> bool:
    """Escalate to a human agent for high-severity issues."""
    return on_call.page(customer_id, reason)

triage_agent = Agent(
    name="Support Triage",
    instructions="Triage inbound support requests. Look up the customer, "
                 "create a ticket, and escalate severity 4 or 5 issues.",
    tools=[lookup_customer, create_ticket, escalate],
    output_type=TriageDecision,
)

result = Runner.run_sync(
    triage_agent,
    "alice@example.com says her production database is unreachable and customers are seeing errors."
)
print(result.final_output)

默认情况下,这会面向 OpenAI 托管模型运行,使用你在 OPENAI_API_KEY 与 SDK 默认设置中配置的模型名。你会看到智能体调用 lookup_customer,然后 create_ticket,然后因为严重度高而 escalate,并发出一个经过验证的 TriageDecision。流程花费几秒钟,产出可路由进你的支持系统的结构化对象。

到目前为止,这是普通的 OpenAI Agents SDK 用法。现在我们换模型。

替换:把 SDK 指向你的本地模型

OpenAI Agents SDK 通过 OpenAIChatCompletionsModel 与 OpenAIResponsesModel 暴露 AsyncOpenAI 客户端。两者都接受 base_url。这就是整个接缝。把客户端指向任何兼容 OpenAI 的端点,SDK 就会以与托管 API 相同的方式使用它进行补全、工具调用与结构化输出。

在本地开发中,Ollama 是阻力最小的路径。它开箱即在 http://localhost:11434/v1 暴露兼容 OpenAI 的端点。

下面是替换。这是把智能体从 OpenAI 托管模型迁移到微调本地模型所需的唯一变化。

from openai import AsyncOpenAI
from agents import set_default_openai_client, set_default_openai_api

client = AsyncOpenAI(base_url="http://localhost:11434/v1", api_key="not-needed")
set_default_openai_client(client)
set_default_openai_api("chat_completions")

triage_agent = Agent(
    name="Support Triage",
    model="ertas-triage-7b",
    instructions="...",
    tools=[lookup_customer, create_ticket, escalate],
    output_type=TriageDecision,
)

五行。Runner.run_sync 调用、工具定义、结构化输出 schema——都没变。智能体现在完全对你笔记本上的模型或你自己的 GPU 实例运行。

为何在这里微调至关重要

如果你只关心成本,完成替换后可以停下来。但你不应该,因为通用开源权重 7B 模型对此类智能体来说还不够好。数字通常以一种特定方式令人失望:模型大多数时候挑对工具,大多数时候填对参数名,大多数时候用对参数值,而"大多数时候"在 5 次调用循环里相乘下来就是 60% 的端到端成功率。

来自公开 BFCL v4 子分数与 Studio 在留出评估集上报告的典型微调后结果,分诊式智能体的代表性区间如下:

通用 Llama 3.1 8B:在广泛工具集上,工具名称与参数名称准确率在 80–85 区间,参数值准确率略低。这些错误率在 5 次调用循环上复合后,端到端任务完成率落在 70 多。
通用 Qwen3-7B / Qwen3-8B:在广泛工具集上,三个子指标都在 80–85 区间。端到端完成率在高 70。
在 400–600 个代表性样本上微调的 Ertas 7B–8B:对于已训练的工具表面,各子指标通常清过 95%。schema 稳定后端到端完成率在 95 左右。

你自己的数字会落在这些区间内的某处,取决于工具数量、schema 复杂度与数据集质量。微调的差距是好玩原型与生产系统之间的差距。95% 的完成率与前沿托管模型在此类有界智能体任务上的表现处于同一区间。79% 的完成率不是。

让你抵达那里的训练数据形态很直接。你需要约 500 个样本,涵盖智能体在生产中实际使用的工具组合:单工具调用(简单情形)、多工具序列(现实情形)、验证边界用例(模型需要识别信息不完整并反问)以及拒绝(模型需要识别超出范围的请求)。Studio 的 Data Craft 模块从结构化提示模板批量生成大部分内容——你手写 30 到 50 个种子样本,其余来自一次有引导的生成,在样本进入数据集前根据你的工具 schema 验证每一个。

500 个样本上对 7B 底座的 QLoRA 微调在标准 GPU 等级上不到一小时完成。Studio 的评估套件根据留出验证集报告上述三个准确率指标,并标记模型仍然薄弱的具体工具/参数组合,以便你针对缺口扩充数据集并运行增量训练。

追踪对等

OpenAI Agents SDK 拥有一个追踪系统,它在统一追踪中捕获每次模型调用、每次工具调用与每次交接。你可以在 OpenAI 仪表板查看追踪,或将其发送到 Logfire、Datadog 或任何 OTLP 后端。

对运维至关重要的事:无论支撑模型是 OpenAI 托管端点还是你的本地 Ollama 服务模型,追踪系统都以相同方式工作。每次模型调用、每次工具调用、每次重试都以相同结构出现在相同追踪 UI 中。你可以在迭代最快的 OpenAI 托管模型上开发智能体,在生产中部署面向你的微调本地模型,并在同一仪表板检视两者的追踪。

这比听起来更重要。智能体团队比应该的时间更长地停留在托管 API 上的原因之一,是面向托管模型的可观测性如此良好——追踪干净、仪表板可用、团队为它建立了肌肉记忆。换出模型的本能被"可观测性层会跟着走"的假设扼杀。在 OpenAI Agents SDK 中,它不会。追踪 UI 是 SDK 的一部分,不是托管模型服务的一部分。

生产部署模式

三种部署模式涵盖了真实智能体产品中遇到的大多数情况。

后端模式:vLLM 在私有端点之后。对于在你服务器上运行并调用你自有基础设施的智能体,正确部署是 vLLM 在单 GPU 实例上提供微调模型,把 OpenAI Agents SDK 指向 vLLM 端点而非 OpenAI。vLLM 的 OpenAI 兼容服务器对工具调用、结构化输出与批处理的支持足够好,可以承担生产流量。单台 A10 实例可承载几百个并发智能体流程,取决于上下文长度。Studio 的导出流程同时产出 GGUF 二进制(用于 Ollama 与 llama.cpp)与原始 safetensors 检查点(用于 vLLM 与 TGI),所以你不必在训练时做出选择。

设备端模式:把模型部署到应用中。对于在用户设备上运行智能体可行的移动与桌面应用,Ertas Deployment CLI 把微调模型作为 GGUF 二进制部署到 iOS、Android、Flutter 或 React Native 项目中,搭配 llama.cpp 的移动绑定。已部署的模型在设备上本地暴露相同的 OpenAI 兼容接口。OpenAI Agents SDK 的 Python 或 TypeScript 代码(通常运行在你控制的后端)在架构需要时指向设备本地端点,或通过一层薄 RPC 桥接到原生运行时。Ertas 文档涵盖两种路径。

混合模式:快路径本地、复杂路径 API。对于工作量分布不均的智能体——大多数任务例行,少数任务异常——正确答案是路由。快路径运行微调本地模型。慢或异常的路径回落到前沿托管模型。OpenAI Agents SDK 让这件事变得干净:用不同的 model 设置定义两个 Agent 实例,写一个顶层路由智能体根据分类进行交接,你就拥有了只对真正需要的调用支付托管 API 价格的架构。实践中这能折叠 80% 到 95% 的 token 成本,同时在确实困难的情况下保留前沿模型行为。

这种组合

OpenAI Agents SDK 是 2026 年 Python 与 TypeScript 智能体代码中开发体验最佳的方案。Ertas 训练的微调模型是生产智能体工作负载中经济模型最佳的方案。它们并非为彼此设计,而这正是它们组合得如此良好的原因——SDK 与模型无关的设计意味着它不需要了解你的模型,而你的微调模型不需要了解 SDK。OpenAI 兼容的 HTTP 接口是契约,只要双方遵守它,其余都是管道。

对于已经在 OpenAI 上做完原型、如今盯着成本曲线的团队,迁移格外无痛。五行配置。一次 Studio 微调。同样的代码、同样的追踪、同样的智能体流程。不同的账单。