1. 从论文到本地跑通：MultiAgentBench 到底在测什么
MultiAgentBench 是一套专门用来评估 LLM agents 协作与竞争能力的基准，配套框架叫 MARBLE（Multi-agent cooRdination Backbone with LLM Engine）。它要解决的问题很直接：以前的 AgentBench、GAIA、ToolBench 这些基准，测的都是单个 agent 的推理和工具调用，但真实场景里往往是多个 agent 一起干活——有的合作写提案，有的在狼人杀里互相骗。单 agent 基准根本测不出这种动态。
MultiAgentBench 的核心设计有三块。第一，多领域覆盖，包含科研协作、Minecraft 建造、数据库错误分析、协同编程四个合作类任务，外加狼人杀和讨价还价两个竞争类任务。第二，它不只算任务完成度，还用基于里程碑的 KPI 来衡量协作质量——每个任务被切成若干里程碑，一个 LLM 检测器持续判断哪些里程碑达成了、是谁贡献的。第三，它支持四种通信拓扑（星型、树型、图型、链型）和四种规划策略（直接提示、CoT、小组讨论、认知自进化规划）。
论文里几个值得记住的结论：gpt-4o-mini 拿到最高平均任务得分；图结构在研究场景中协调效果最好；认知规划把里程碑达成率提升了约 3%；小组讨论反而在所有指标上垫底，作者猜测是规划组太大拖了后腿。这些结论你想在本地复现，就需要一套能切换模型、切换拓扑、切换规划策略的实验环境。
问题来了：MARBLE 要跑多模型对照，你得同时接 OpenAI、Together AI 等好几家 API，每家的 Key、Base URL、模型名格式都不一样。我试过手动改环境变量切来切去，跑一组对照实验光配置就耗掉半小时。下面这套流程用 TaoToken 统一 Key 来管多模型，把配置成本压到最低。
2. 前置准备：TaoToken 统一 Key 与 MARBLE 环境搭建
MARBLE 的代码在 GitHub 上公开（ulab-uiuc/MARBLE），clone 下来之后你会发现它依赖函数调用能力，所以选的模型必须支持 function calling。论文里用了 Meta-Llama-3.3-70B、Meta-Llama-3.1-70B-Instruct-Turbo、Meta-Llama-3.1-8B-Instruct-Turbo、GPT-3.5-turbo-0125 和 GPT-4o-mini 五个模型。你自己复现时不一定要全跑，选两三个做对照就够。
关键问题是这些模型分散在不同供应商。OpenAI 的走官方 API，Llama 系列论文里走的是 Together AI。如果你要加 DeepSeek 系列做扩展实验，又是另一个端点。TaoToken 的作用是把这些统一到一个 API 入口，你只需要一个 Key，通过改 model 参数就能切换底层模型。
先去 TaoToken 控制台创建一个 API Key。地址是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，登录后在 API Keys 页面点创建，复制出来的 Key 形如sk-xxxxxxxx。这个 Key 同时能调 GPT 系列、Claude 系列和主流开源模型，省掉你分别注册多家平台的麻烦。
拿到 Key 之后，在 MARBLE 项目根目录建一个.env文件。MARBLE 的配置读取逻辑在marble/configs/下面，不同场景有各自的 config 文件，但 API 相关的环境变量是全局的。你需要设置三个核心变量：Base URL 指向 TaoToken 的 API 端点，API Key 填你刚创建的，模型名按场景 config 里的字段来。
# .env 文件，放在 MARBLE 项目根目录 OPENAI_API_KEY=sk-你的TaoToken密钥 OPENAI_BASE_URL=https://taotoken.net/api # 如果 MARBLE 代码里用的是 openai 库的 client 初始化 # 它会自动读取上面两个环境变量这里有个坑要注意：MARBLE 部分模块可能硬编码了https://api.openai.com/v1，你需要全局搜一下base_url或api_base关键字，把它改成从环境变量读取。通常在marble/agents/或marble/llm/目录下的 client 初始化代码里。改完之后，所有走 OpenAI 兼容接口的模型调用都会经过 TaoToken。
模型清单方面，你需要在场景 config 里指定每个 agent 用哪个模型。以研究场景为例，config 文件里会有类似agent_model: "gpt-4o-mini"的字段。如果你想做多模型对照，就复制一份 config，把模型名换成Meta-Llama-3.3-70B或DeepSeek系列。TaoToken 支持的模型 ID 可以在模型对话页面查到：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=chat&utm_campaign=rewrite ，页面上能直接切换模型看效果，确认哪个模型 ID 可用再写进 config。
Python 环境用 3.10 以上，依赖装法：
git clone https://github.com/ulab-uiuc/MARBLE.git cd MARBLE python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate pip install -r requirements.txt如果 requirements 里有openai库，确认版本在 1.0 以上，因为新版才支持base_url参数。装完后跑一个最小连通性测试，确认 Key 和 Base URL 配对了。
3. 可复制配置：环境变量、模型清单与运行命令
这一节给你一份能直接抄的配置。MARBLE 的配置分两层：全局环境变量管 API 接入，场景 config 管 agent 角色、拓扑结构和规划策略。
先看全局环境变量。除了上面.env里的两个变量，如果你用 python-dotenv 加载，在入口脚本里加一行from dotenv import load_dotenv; load_dotenv()。有些 MARBLE 版本用的是OPENAI_API_BASE而不是OPENAI_BASE_URL，两个都设上最保险：
# .env 完整版 OPENAI_API_KEY=sk-你的TaoToken密钥 OPENAI_BASE_URL=https://taotoken.net/api OPENAI_API_BASE=https://taotoken.net/api接下来是场景 config。MARBLE 的 config 通常是 JSON 或 YAML 格式，放在marble/configs/下。以研究场景为例，一份精简的 config 长这样：
{ "scenario": "research", "coordination_protocol": "graph", "planning_strategy": "cognitive_evolving", "max_iterations": 5, "max_communication_iterations": 5, "agents": [ { "name": "planner", "role": "project_manager", "model": "gpt-4o-mini", "max_token_num": 1024, "temperature": 0.7, "top_p": 1.0 }, { "name": "researcher_a", "role": "domain_expert", "model": "gpt-4o-mini", "max_token_num": 1024, "temperature": 0.7, "top_p": 1.0 }, { "name": "researcher_b", "role": "technical_specialist", "model": "Meta-Llama-3.3-70B", "max_token_num": 1024, "temperature": 0.7, "top_p": 1.0 } ], "graph_edges": [ ["planner", "collaborates", "researcher_a"], ["planner", "collaborates", "researcher_b"], ["researcher_a", "collaborates", "researcher_b"] ] }这份 config 里，coordination_protocol可选star、tree、graph、chain；planning_strategy可选vanilla、cot、group_discussion、cognitive_evolving。你要复现论文里“图结构最好”的结论，就把 protocol 设成graph；要对比认知规划的效果，就把 strategy 在cot和cognitive_evolving之间切换。
模型清单方面，TaoToken 上可用的模型 ID 直接写进model字段。做多模型对照时，建议固定其他变量，只改一个 agent 的模型，这样能隔离出模型能力的影响。比如上面 config 里 researcher_b 用 Llama，其他用 gpt-4o-mini，跑完对比 researcher_b 的 KPI 贡献。
运行命令：
# 单场景运行 python -m marble.run --config marble/configs/research_graph_cognitive.json # 批量对照实验，写个 shell 脚本循环 for model in gpt-4o-mini Meta-Llama-3.3-70B DeepSeek; do sed "s/\"model\": \"gpt-4o-mini\"/\"model\": \"$model\"/g" \ marble/configs/research_graph_cognitive.json > /tmp/config_$model.json python -m marble.run --config /tmp/config_$model.json \ --output results/research_$model.json done跑之前确认max_iterations别设太大。论文消融实验显示，Minecraft 场景迭代到 7 次时任务和协调得分最高，到 10 次反而急剧下降，20 次任务分回升但协调分不再涨。研究场景论文设的是 5 次，你复现时保持 5 就行，别为了“跑充分”调到 20，那样反而引入通信开销导致协调退化。
4. 验证请求与结果校验：确认多模型对照跑通
配置写完，先做一次最小验证，确认请求真的打到了 TaoToken 并且模型返回正常。MARBLE 跑起来后会在控制台打印每个 agent 的通信日志，你重点看两个东西：一是请求有没有报错，二是返回的 JSON 里有没有choices字段。
最直接的验证方式是单独调一次 API，不经过 MARBLE 的复杂流程：
from openai import OpenAI import os from dotenv import load_dotenv load_dotenv() client = OpenAI( api_key=os.getenv("OPENAI_API_KEY"), base_url=os.getenv("OPENAI_BASE_URL") ) resp = client.chat.completions.create( model="gpt-4o-mini", messages=[{"role": "user", "content": "回复 OK 两个字母"}], max_tokens=10 ) print(resp.choices[0].message.content)如果打印出OK，说明 Key 和 Base URL 没问题。换成Meta-Llama-3.3-70B再跑一次，确认开源模型也能通。这一步过了，再跑 MARBLE 全流程。
MARBLE 跑完后会在results/目录生成 JSON 结果文件。结果里包含每个 agent 的里程碑贡献数n_j、总体 KPI、任务得分 TS、通信得分 C_score、规划得分 P_score 和协调得分 CS。校验时按论文公式对一遍：
import json with open("results/research_gpt-4o-mini.json") as f: result = json.load(f) # 论文公式：KPI_overall = (1/(N*M)) * sum(n_j) N = len(result["agents"]) M = result["total_milestones"] n_j_sum = sum(a["milestones_contributed"] for a in result["agents"]) kpi_calc = n_j_sum / (N * M) print(f"论文公式算出的 KPI: {kpi_calc:.4f}") print(f"框架报告的 KPI: {result['kpi_overall']:.4f}") # 两者应该一致，不一致说明里程碑检测或统计逻辑有问题协调得分 CS 是 C_score 和 P_score 的平均值，也校验一下：
cs_calc = (result["communication_score"] + result["planning_score"]) / 2 print(f"CS 校验: {cs_calc:.2f} vs {result['coordination_score']:.2f}")多模型对照的结果对比，建议拉个表格。把每个模型在每个场景的 TS 和 CS 填进去，看趋势是否符合论文结论。比如论文说 gpt-4o-mini 在研究场景 TS 是 84.13%，你跑出来如果差太多（比如低于 70%），可能是里程碑检测的 prompt 没对齐，或者模型版本变了。这时候去检查marble/evaluation/下的里程碑检测逻辑，确认它用的判定 prompt 和论文附录 A.4 一致。
还有一个容易忽略的点：论文里每个 agent 的长期记忆设为无限，通信轮次上限 5。你复现时如果记忆被截断，agent 会“忘掉”之前的里程碑进展，导致 KPI 偏低。检查 config 里有没有memory_limit字段，设成null或unlimited。
5. 常见报错排查：401、local proxy failed 与 choices 解析失败
跑多模型对照时，报错集中在几个地方。下面按真实遇到的错误逐个拆。
401 Authentication Error。这个最常见，说明 Key 没被正确读取。先确认.env文件在项目根目录而不是子目录，然后确认代码里真的调用了load_dotenv()。如果用的是 MARBLE 自带的 config 加载器，它可能从os.environ直接读，那你就得在 shell 里export OPENAI_API_KEY=sk-xxx而不是只写.env。还有一种情况：Key 复制时带了空格或换行，用print(repr(os.getenv("OPENAI_API_KEY")))检查一下首尾字符。
local proxy failed / Connection error。这个报错通常出现在你本地有网络代理设置，但代理没生效或配置冲突。检查环境变量里有没有HTTP_PROXY、HTTPS_PROXY、ALL_PROXY，如果有但代理服务没开，请求就会失败。临时清掉这些变量再跑：
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY python -m marble.run --config your_config.json如果清掉后能通，说明是代理配置问题。另外确认OPENAI_BASE_URL写的是https://taotoken.net/api，不要多加/v1或结尾斜杠，不同库对 URL 拼接的处理不一样，多写的路径会导致 404 而不是 401，报错信息会误导你以为是 Key 的问题。
reading 'choices' 报错 / KeyError: 'choices'。这个说明 API 返回的 JSON 结构和你代码预期的不一样。正常返回是{"choices": [{"message": {...}}]}，如果返回的是{"error": {...}}，代码去取choices就会 KeyError。根因通常是模型 ID 写错了，TaoToken 找不到这个模型就返回错误对象。去模型对话页面确认模型 ID 的准确拼写，注意大小写和连字符。比如Meta-Llama-3.3-70B和meta-llama-3.3-70b可能不一样，以页面上显示的为准。
OAuth / token expired。如果你用的是 Claude Code 或某些需要 OAuth 流程的工具接 MARBLE，可能会遇到 token 过期。这类工具建议直接用 API Key 模式而不是 OAuth。在 TaoToken 控制台重新生成一个 Key，确保它有调用目标模型的权限。如果用的是 Coding Plan 做长期实验，确认套餐覆盖了你需要的模型：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。
里程碑检测返回空。MARBLE 跑完但 KPI 是 0，说明里程碑检测器没识别出任何达成项。检查检测器用的模型是否支持结构化输出，有些小模型返回的 JSON 格式不规范，解析失败就静默返回空。把检测器模型换成 gpt-4o-mini 试试，它的 JSON 遵循度更好。另外确认total_milestones字段不为 0，如果任务配置里没定义里程碑，检测器无从判断。
排查顺序建议：先单独调 API 确认连通性，再跑单 agent 单场景确认流程，最后才上多模型对照。这样出错时能快速定位是接入层还是业务层的问题。
6. 从复现到扩展：把 MARBLE 用到你自己的 agent 场景
跑通论文复现只是起点，MARBLE 的框架设计允许你接入自有场景。扩展路径有三条：加新任务、加新拓扑、加新规划策略。
加新任务需要实现一个场景类，定义 agent 角色、里程碑列表和评估函数。MARBLE 的场景接口在marble/scenarios/下，你照着research或coding的实现抄一份，改掉里程碑定义和评分逻辑就行。里程碑定义是关键——论文里研究场景的里程碑是“完成 5 个关键问题”，你的场景可以是“完成需求分析”“通过单元测试”“生成文档”这类可检测的节点。每个里程碑要能被 LLM 检测器判断是否达成，所以描述要具体，别写“代码质量好”这种模糊标准。
加新拓扑需要改 Agent Graph 模块。论文支持星、树、图、链四种，核心是定义 agent 之间的边关系。你可以在 config 的graph_edges里自定义任意连接方式，比如环形、全连接、分层混合。改完后确认通信模块只允许有边相连的 agent 之间传递消息，否则就退化成全广播了。
加新规划策略需要改 Cognitive Module 里的 prompt 模板。论文的四种策略本质是四套不同的 planning prompt。你可以在marble/prompts/下加一个新模板，比如“辩论式规划”——让两个 agent 先对立辩论再综合。然后在 config 的planning_strategy里注册这个新策略名。
做多模型对照实验时，建议固定随机种子。MARBLE 的 agent 行动有 temperature=0.7 的随机性，同一 config 跑两次结果可能不同。在 config 里加"seed": 42，并在 LLM 调用时传seed参数（OpenAI 兼容接口支持）。这样你的对照实验才有可重复性。
最后提醒一个实操细节：跑大规模对照实验时，API 调用量大，注意控制并发。MARBLE 默认可能是串行调用，一个研究场景 5 个 agent、5 轮迭代、每轮多次通信，单次实验就是几十到上百次 API 调用。多模型多场景跑下来轻松上千次。用 TaoToken 的好处是统一计费和限流，你可以在控制台看到用量，避免某一家突然限流打断实验。如果要做长期反复的 agent 实验，Coding Plan 的额度模式比按次计费更划算。
扩展场景跑通后，把结果和论文基线对比，如果趋势一致（比如图结构确实比树结构好、认知规划确实提升 KPI），说明你的复现是可信的，这时候再往自有场景迁移就有底气了。
