AutoGen 接入统一 API:base_url 与 model_info

先说结论:base_url 加 model_info

当前 AutoGen(0.4+ 重写版本)在 autogen-ext 包的 OpenAIChatCompletionClient 上配置模型。两个参数承担了自定义端点的场景:base_url,文档里写明模型不托管在 OpenAI 时必填;model_info,文档里写明模型名不是有效 OpenAI 模型时必填。base_url 填 https://api.kkaiapi.com/v1,传 Key,再声明这个模型能做什么。 model_info 是简化版配置最容易漏掉的部分。对 claude-sonnet-4-6 这样的 ID,AutoGen 没有内置的能力记录,所以要自己声明:是否支持视觉、函数调用、JSON 输出、结构化输出,以及属于哪个模型家族。非 OpenAI 的 ID 缺了这个字典,客户端构造阶段就会失败,请求还没发出去。

import os
from autogen_ext.models.openai import OpenAIChatCompletionClient

client = OpenAIChatCompletionClient(
    model="claude-sonnet-4-6",            # 目录里任意 ID
    base_url="https://api.kkaiapi.com/v1",
    api_key=os.environ["KKAIAPI_KEY"],
    model_info={
        "vision": False,
        "function_calling": True,
        "json_output": True,
        "structured_output": True,
        "family": "unknown",
    },
)

一个客户端,整个运行时的每个 Agent

AutoGen(GitHub 上的 microsoft,约 6 万星标)把多智能体系统构建成对话:会推理和调用工具的 AssistantAgent,像 RoundRobinGroupChat 和 SelectorGroupChat 这样在 Agent 之间传递工作的团队,以及决定对话何时结束的终止条件。每个 Agent 轮次、每次 selector 决策、每次工具调用往返,都是一次经由 Agent 持有的模型客户端发出的 chat-completions 请求。 这套架构让模型客户端成为路由的唯一入口。一个构造好的 OpenAIChatCompletionClient 可以在 Agent 之间共享,也可以让每个 Agent 各自持有自己的客户端和不同的模型 ID:规划者用 claude-opus-4-7,工作 Agent 用 gpt-5.4-mini,格式化 Agent 用 glm-5.2,全部经同一个 base_url 和 Key。model 字段原样传下去,一个团队内部混用厂商就是构造参数,不是新增依赖。 group-chat 的 selector 值得单独说一句:SelectorGroupChat 用一个模型来决定下一个发言者,这个 selector 模型每一轮都会触发。这是一个高频、低难度的席位,正好该放一个快速的 ID。

完整配置:两 Agent 团队与 legacy config_list

下面这个团队示范了基本形状:每个 Agent 对着同一个端点持有自己的客户端,判断力集中的地方放强模型,不需要的地方放快速模型。同一个客户端对象也驱动用工具的 AssistantAgent;工具 schema 走标准请求,所以只要 model_info 声明了函数调用能力,任意 ID 都能用工具。 legacy 版本(AutoGen 0.2 以及延续它的 AG2 分支)通过 config_list 字典配置模型:model、base_url、api_key,以及设成 "openai" 的 api_type,每个条目一份。如果你的代码库把 llm_config 传给 ConversableAgent,用的就是这套 API;同样的端点和 ID 都能用,只是表达成字典键而不是构造参数。

import os, asyncio
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_agentchat.conditions import MaxMessageTermination
from autogen_ext.models.openai import OpenAIChatCompletionClient

def gateway_client(model_id: str) -> OpenAIChatCompletionClient:
    return OpenAIChatCompletionClient(
        model=model_id,
        base_url="https://api.kkaiapi.com/v1",
        api_key=os.environ["KKAIAPI_KEY"],
        model_info={"vision": False, "function_calling": True,
                    "json_output": True, "structured_output": True,
                    "family": "unknown"},
    )

planner = AssistantAgent("planner", model_client=gateway_client("claude-opus-4-7"))
worker = AssistantAgent("worker", model_client=gateway_client("gpt-5.4-mini"))

team = RoundRobinGroupChat([planner, worker],
                           termination_condition=MaxMessageTermination(8))
print(asyncio.run(team.run(task="给功能开关起草一份上线计划。")))

按 Agent 选模型

多智能体对话每一轮都会重发不断增长的转录,这让模型摆放的影响会复合:同一个 ID 放在话多的席位,花费是放在安静席位的数倍。按 Key 的用量视图能看到每个模型的 token,直接对应到席位,是决定怎么重新调整摆放的证据。

• 规划者和评审 Agent 承载团队的判断力;claude-opus-4-7 和 gpt-5.5 属于这些席位,因为一个糟糕的计划或一次敷衍的评审会传播到后续每一轮
• 执行范围明确子任务的工作 Agent 是走量席位,gpt-5.4-mini 和 glm-5.2 能压平每轮成本;团队的转录记录随每一轮增长,走量席位主导 token 花费
• 用工具的 Agent 需要可靠的函数调用;claude-sonnet-4-6 是可靠的中间档,model_info 里的 function_calling 要如实声明
• SelectorGroupChat 的发言人选择模型每轮都在简单任务上触发一次,给这个席位配你手头最快的可用 ID,而不是让它默认继承团队最强的模型

主力模型价格

价格按 kkaiapi 中文区实时价格计算,单位 ¥/1M tokens(输入/输出)。

翻车点与版本锁定

漏掉 model_info。用一个非 OpenAI 的 ID,客户端会在构造阶段直接报错,因为它没法查到一个认不出的名字对应什么能力。解决办法是如实声明这份字典:在一个不支持函数调用的模型上把 function_calling 写成 true,会在后面产生格式错误的工具调用循环,这比一开始就报错更难排查。 两个 AutoGen,一个名字。0.4+ 重写版本(autogen-agentchat 和 autogen-ext 两个包)和延续 0.2 谱系的 AG2 分支共用一个名字,不共用一套 API。教程经常混着讲两代写法,导入语句是分辨的线索:autogen_agentchat 和 autogen_ext 配上客户端构造器,是当前的 0.4+ API;裸的 autogen 导入配 config_list 和 llm_config,是 legacy 谱系。给当前 API 锁定 autogen-agentchat 加 autogen-ext[openai] 这一对,不要把 legacy 包装进同一个环境。 base_url 没带 /v1。客户端会在你给的 base 后面拼接路由路径,裸 host 会产生连接或 404 形状的失败。https://api.kkaiapi.com/v1 在 0.4 构造器和 legacy config_list 条目里都是正确的值。 脚本里的 async 意外。0.4 版本的 API 是 async-first 的,团队运行返回协程。脚本里不带事件循环直接调用 team.run() 拿到的是一个协程对象,不是结果。asyncio.run() 是最小的包装,如上面示例所示。 没设边界的团队会烧掉没设边界的 token。终止条件是成本控制的一部分,不只是正确性:一个没有终止条件、或者终止条件很宽松又配了话多的模型的团队,会一直重发不断增长的转录。在扩大规模之前先设好 MaxMessageTermination 或等价的护栏。

哪些人会把 AutoGen 接到一个网关上

• 构建混合厂商 Agent 系统的团队,旗舰规划者配快速工作 Agent,不用给每家厂商各维护一套 SDK 和凭证
• 对比团队组成的研究者,每种候选摆放都是构造参数,按 Key 用量自动给每次实验定价
• 在迁移 legacy config_list 代码库的工程师,同一个端点在过渡期内同时服务两代 API
• 运营长时间跑或定时跑的 Agent 团队的团队,转录会复合增长,一个计费面能让每个模型的花费保持清晰可见
• 手头没有某家厂商官方支付渠道的开发者,充值即用不需要海外卡

验证接入与排查首次团队运行

接线 Agent 之前先列出网关的模型;model 参数必须和提供的某个 ID 精确匹配,版本后缀也算。 首次运行的失败很有规律。构造阶段就报错、点名模型能力,说明一个非 OpenAI 的 ID 缺了 model_info。对网关报 401,是客户端解析到的 Key 不对,先打印实际生效的 base_url 再去换 Key。模型不存在的报错是 ID 拼错了。拿到一个协程对象而不是预期的结果,是 async-first 的 API 遇到了同步脚本。工具调用产生格式错误,通常能追溯到一个 model_info 里夸大了自己能力的模型。 团队跑起来之后,kkaiapi 控制台会显示每次请求的模型、token 数和花费。多智能体的转录会让 token 增长超线性于对话轮数,用量视图里按模型的拆分是最快看出哪个席位在扛账单、终止条件有没有起作用的地方。

curl -s https://api.kkaiapi.com/v1/models \
  -H "Authorization: Bearer $KKAIAPI_KEY" | head -50

常见问题