1. 为什么我要在本地复现 CL-bench：上下文学习基准到底测什么
CL-bench 是 Shunyu Yao 加入 HY 之后的首个作品，它想回答一个很朴素但一直被绕开的问题：模型能不能从你给它的上下文里学新东西，然后用这个新知识去解题。注意，这里说的不是提示工程，也不是传统意义上的 ICL（In-Context Learning，上下文学习）——那两种范式更多是让模型从少量输入输出示例里推断任务格式，靠的还是预训练阶段已经见过的知识。CL-bench 要测的是另一件事：上下文里塞的是模型预训练时压根没见过的新知识，比如一个虚构国家的完整法律体系、一个新造的金融工具规则、一份刚发布的产品手册，模型必须现场读懂、内化，再拿它去裁决案件、做财务分析或者排故障。
论文给出的数字挺扎心：十个前沿模型平均任务解决率只有 17.2%，表现最好的 GPT-5.1 也才 23.7%。而且错误分析里，上下文误用率在所有模型上都超过 60%，格式错误在 GPT-5.1 上超过 35%。这意味着模型不是"不会推理"，而是"没把上下文当回事"——要么忽略上下文里的新知识，要么错误地套用。
我关注这个基准，是因为它跟日常做 Agent、做 RAG、做长文档问答的场景高度重合。你在生产里遇到的很多失败，本质就是模型没从你喂的上下文里学到该学的东西。所以我想在本地把 CL-bench 跑起来，用统一的 Key 通道去复现评测任务，观察模型在少样本、长上下文场景下的真实短板。这篇就交付一套可复制的环境配置、基准运行命令和结果验证步骤，你跟着做就能在自己机器上跑通。
CL-bench 的规模是 500 个复杂上下文、1,899 个任务、31,607 条验证规则，平均每个上下文 3.8 个任务，每个任务 16.6 条评分规则，平均输入长度 10.4K tokens，最长能到 65.0K tokens。这个体量决定了你不能随便找个网页版对话框就测，必须走 API 通道批量跑，而且要能控制 Base URL 和模型 ID，方便横向对比不同模型。这也是我选择用 TaoToken 统一 Key 的原因：一个 Key 通道覆盖多个模型，切换模型只改一个 Model ID，评测脚本不用动。
2. TaoToken 前置准备：统一 Key 与 Base URL 的接入方式
在跑 CL-bench 之前，得先把模型调用通道打通。我用的方式是 TaoToken 的统一 API 通道，它的好处是 Base URL 固定，模型通过 Model ID 区分，这样我在评测脚本里只需要维护一份配置，换模型就是换一个字符串。对于 CL-bench 这种要横向对比十个模型的场景，这一点能省掉大量重复配置工作。
先说清楚要准备什么。你需要一个可用的 API Key，以及两个固定地址：官网是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 根地址是 https://taotoken.net/api 。注意 API 地址后面不加任何 UTM 参数，保持干净，避免某些 SDK 把查询串带进签名导致 401。
Key 的获取走控制台，地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，进去之后在 API Keys 页面创建，地址是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。创建完把 Key 复制出来，形如sk-开头的一串字符，只显示一次，丢了就重建。
这里有个我踩过的坑：很多人把 Key 直接写进脚本里然后提交到 Git，结果泄露。正确做法是写进环境变量或者.env文件，并且把.env加进.gitignore。CL-bench 的评测脚本会读环境变量，所以下面统一用环境变量方式。
关于模型选择，CL-bench 论文里评估的是推理模式下的模型，所以你在选 Model ID 时要挑支持推理的版本。TaoToken 的模型列表可以在文档里查，地址是 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。如果你只是想先验证通道通不通，可以用模型对话页面手动发一条消息，地址是 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite ，确认返回正常再进脚本。
如果你打算长期跑评测、做 Agent 类的批量任务，可以考虑 Coding Plan，地址是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，它在高频调用场景下更划算。但如果你只是复现 CL-bench 跑一轮，按量付费的 API Key 就够了。
还有一个细节：CL-bench 的输入最长 65K tokens，所以你要确认所选模型的上下文窗口足够大。如果模型窗口只有 32K，长上下文那部分任务会直接截断，结果不可比。这一点在配置阶段就要确认，别等跑完才发现一半任务被截了。
3. 可复制配置：环境变量、Base URL 与评测脚本参数
这一节是核心，我把配置拆成三块：环境变量、Python 依赖、评测脚本参数。你按顺序做就行。
先配环境变量。在项目根目录建一个.env文件，内容如下：
# .env TAOTOKEN_API_KEY=sk-你的Key TAOTOKEN_BASE_URL=https://taotoken.net/api CLBENCH_MODEL_ID=gpt-5.1 CLBENCH_DATA_DIR=./data/cl-bench CLBENCH_OUTPUT_DIR=./outputs CLBENCH_MAX_TOKENS=8192 CLBENCH_TEMPERATURE=0.0注意TAOTOKEN_BASE_URL结尾不要带斜杠，SDK 拼接路径时容易出双斜杠。CLBENCH_MODEL_ID先填一个，后面横向对比时用命令行覆盖。
然后是 Python 依赖。CL-bench 官方仓库用到的库不多，主要是openai、datasets、tqdm、pandas。建一个requirements.txt：
openai>=1.30.0 datasets>=2.19.0 tqdm>=4.66.0 pandas>=2.2.0 python-dotenv>=1.0.0安装命令：
python -m venv venv source venv/bin/activate pip install -r requirements.txt接下来是评测脚本的配置。CL-bench 的调用走 OpenAI 兼容接口，所以直接用openaiSDK，把base_url指向 TaoToken。核心配置片段如下：
import os from dotenv import load_dotenv from openai import OpenAI load_dotenv() client = OpenAI( api_key=os.getenv("TAOTOKEN_API_KEY"), base_url=os.getenv("TAOTOKEN_BASE_URL"), ) MODEL_ID = os.getenv("CLBENCH_MODEL_ID", "gpt-5.1") def call_model(context: str, task: str) -> str: resp = client.chat.completions.create( model=MODEL_ID, messages=[ {"role": "system", "content": "You are a careful reasoner. Read the provided context and answer the task strictly based on it."}, {"role": "user", "content": f"# Context\n{context}\n\n# Task\n{task}"}, ], temperature=float(os.getenv("CLBENCH_TEMPERATURE", "0.0")), max_tokens=int(os.getenv("CLBENCH_MAX_TOKENS", "8192")), ) return resp.choices[0].message.content这段代码里，base_url和api_key都从环境变量读，模型 ID 也是。这样你换模型时只改.env或者命令行传参，脚本本身不动。
如果你用的是 Claude Code 这类工具做辅助开发，它的配置也是三件套：Base URL 填https://taotoken.net/api，Key 填你的sk-，Model ID 填你要用的模型。Claude Code 的接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 里有说明，照着填就行。注意 Claude Code 走的是 Anthropic 兼容格式，如果你要用它跑 CL-bench 的辅助脚本，确认 SDK 用的是对应协议。
还有一个容易忽略的点：CL-bench 的评分规则有 31,607 条，验证器用的是 GPT-5.1。如果你本地也要跑验证，验证器调用同样走 TaoToken，但建议用不同的 Key 或者至少不同的 Model ID，避免和被测模型混在一起导致限流。我一般把验证器单独放一个.env.verifier，里面CLBENCH_MODEL_ID设成验证模型。
配置完成后，先跑一个连通性测试：
python -c " from openai import OpenAI import os from dotenv import load_dotenv load_dotenv() c = OpenAI(api_key=os.getenv('TAOTOKEN_API_KEY'), base_url=os.getenv('TAOTOKEN_BASE_URL')) r = c.chat.completions.create(model=os.getenv('CLBENCH_MODEL_ID'), messages=[{'role':'user','content':'ping'}], max_tokens=16) print(r.choices[0].message.content) "返回任何非空内容就说明通道通了。如果报 401，检查 Key 有没有多余空格；如果报连接错误，检查 Base URL 是不是写成了带路径的形式。
4. 跑通评测任务：从单条样本到全量基准的验证步骤
配置通了之后，先别急着跑全量。CL-bench 有 1,899 个任务，全量跑一轮成本不低，而且如果脚本有 bug，你会浪费大量调用。正确做法是先跑单条样本，确认输入输出和评分逻辑都对，再放大。
第一步，下载数据。CL-bench 的数据集在 HuggingFace 上，用datasets拉：
from datasets import load_dataset ds = load_dataset("cl-bench/cl-bench", split="test") print(ds[0].keys()) print(len(ds))如果网络拉取慢，可以先下载到本地再load_from_disk。数据字段一般包含context、task、rubric（评分规则）、category、subcategory。先打印一条看看结构，确认字段名和脚本里用的一致。
第二步，跑单条样本。取第一条数据，调用模型，把输出和评分规则一起打印：
sample = ds[0] output = call_model(sample["context"], sample["task"]) print("=== MODEL OUTPUT ===") print(output) print("=== RUBRIC ===") print(sample["rubric"])这一步你要人工看一眼：模型有没有按上下文回答，还是靠预训练知识瞎编。CL-bench 的很多任务上下文是虚构的，如果模型输出里出现了上下文没提过的"常识"，那基本就是上下文忽略，属于论文里说的主要失败模式。
第三步，接验证器。CL-bench 用 GPT-5.1 做验证器，把模型输出和评分规则一起喂给验证器，让它逐条判断是否满足。验证器调用同样走 TaoToken，但建议单独配置：
verifier_client = OpenAI( api_key=os.getenv("TAOTOKEN_API_KEY"), base_url=os.getenv("TAOTOKEN_BASE_URL"), ) def verify(output: str, rubric: str) -> dict: prompt = f"""You are a strict grader. Given the model output and the rubric, judge each rule as pass or fail. # Model Output {output} # Rubric {rubric} Return JSON: {{"passed": <int>, "total": <int>, "details": [...]}}""" resp = verifier_client.chat.completions.create( model="gpt-5.1", messages=[{"role": "user", "content": prompt}], temperature=0.0, response_format={"type": "json_object"}, ) return resp.choices[0].message.content第四步，批量跑。用tqdm包一层，逐条跑并写结果到 JSONL：
import json from tqdm import tqdm results = [] for i, sample in enumerate(tqdm(ds)): try: out = call_model(sample["context"], sample["task"]) score = verify(out, sample["rubric"]) results.append({ "id": i, "category": sample["category"], "subcategory": sample["subcategory"], "output": out, "score": score, }) except Exception as e: results.append({"id": i, "error": str(e)}) if i % 50 == 0: with open(os.path.join(os.getenv("CLBENCH_OUTPUT_DIR"), "results.jsonl"), "w") as f: for r in results: f.write(json.dumps(r, ensure_ascii=False) + "\n")注意每 50 条落一次盘，避免中途崩了全丢。全量跑完后，用 pandas 汇总：
import pandas as pd df = pd.read_json("outputs/results.jsonl", lines=True) df["passed"] = df["score"].apply(lambda x: json.loads(x)["passed"] if isinstance(x, str) else 0) df["total"] = df["score"].apply(lambda x: json.loads(x)["total"] if isinstance(x, str) else 1) df["rate"] = df["passed"] / df["total"] print(df.groupby("category")["rate"].mean()) print("Overall:", df["rate"].mean())跑完之后你会看到类似论文里的分布：领域知识推理相对高，经验发现与模拟最低。我实测下来，长上下文那部分任务掉分最明显，尤其是输入超过 30K tokens 之后，模型开始丢上下文里的细节。
5. 常见报错排查：401、local proxy failed、reading choices、OAuth
跑评测的过程中，报错基本集中在几类。我把真实遇到过的和对应的排查路径列出来，你对照着看。
第一类，401 Unauthorized。最常见的原因是 Key 写错或者带了多余字符。检查.env里TAOTOKEN_API_KEY有没有引号、空格、换行。另一个原因是 Base URL 写成了带路径的形式，比如https://taotoken.net/api/v1，而 SDK 自己会拼/v1，结果变成/api/v1/v1/chat/completions，服务端认不出就返回 401。正确写法就是https://taotoken.net/api，不带/v1。
第二类，local proxy failed或者连接超时。这类报错通常是本地网络环境或者代理配置导致的。检查你的 shell 里有没有HTTP_PROXY、HTTPS_PROXY环境变量，如果有，SDK 会走代理，而代理可能不通。临时清掉：
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY然后重跑连通性测试。如果清了就通，说明是代理问题，后续脚本里显式不读代理即可。
第三类，reading 'choices'或者KeyError: 'choices'。这个报错说明返回体里没有choices字段，通常是服务端返回了错误 JSON，但 SDK 没抛异常直接让你取字段。根因可能是模型 ID 写错，服务端返回了{"error": ...}。排查方法是在call_model里先打印resp的原始内容：
resp = client.chat.completions.create(...) print(resp.model_dump())看返回体里error字段写了什么。常见的是model not found，那就是 Model ID 拼错了，去文档页核对。
第四类，OAuth 相关报错。如果你用的是 Claude Code 或者某些 CLI 工具，它们可能默认走 OAuth 登录而不是 API Key。这时候要在配置里显式指定 API Key 模式，把 Base URL 和 Key 填进对应的配置文件。Claude Code 的配置三件套是 Base URL、Key、Model ID，缺一不可。如果只填了 Key 没填 Base URL，它会去连默认端点，然后报 OAuth 失败。具体配置路径在文档页有说明，照着改。
第五类，长上下文任务报context length exceeded。这是模型窗口不够，不是通道问题。解决办法是换更大窗口的模型，或者在脚本里对超长上下文做截断并记录，但截断后的结果不能和全量结果混在一起比较，要单独标注。
第六类，验证器返回的 JSON 解析失败。response_format={"type": "json_object"}不是所有模型都支持，如果验证模型不支持，返回的可能是带 markdown 代码块的文本。这时候要加一层清洗：
import re def parse_json_safe(text): text = re.sub(r"^```json\s*|\s*```$", "", text.strip()) return json.loads(text)排查顺序建议是：先跑连通性测试确认通道，再跑单条样本确认脚本逻辑，最后才全量。每一步都落盘，出问题能定位到具体哪条。
6. 结果验证与下一步：用统一 Key 做横向对比
跑完一轮之后，你要验证结果是否可信。CL-bench 论文里提到验证器和人工抽样的一致率超过 90%，所以你本地跑出来的分数如果和论文差距很大，先别怀疑模型，先检查验证器配置。验证器用的模型、温度、prompt 模板都会影响分数。我建议固定验证器配置，只改被测模型，这样横向对比才有意义。
横向对比的做法很简单：把.env里的CLBENCH_MODEL_ID换成另一个模型，重跑脚本，输出到不同的目录。因为 Base URL 和 Key 都没变，你不需要重新配置通道，只改一个字符串。这就是统一 Key 通道的价值——评测脚本、验证器、数据加载全都不动，只换模型 ID。
对比时重点看三个维度：整体解决率、分类别解决率、错误类型分布。论文里说上下文误用率超过 60%，你在本地跑的时候可以统计模型输出里有多少次引用了上下文没提过的内容，这个指标比单纯看分数更能说明问题。具体做法是在验证 prompt 里加一条"判断输出是否引用了上下文之外的知识"，让验证器一起判。
如果你要长期做这类评测，建议把配置抽成一个config.yaml，模型列表、验证器模型、输出路径都放进去，跑的时候用命令行参数覆盖。这样你可以写一个循环，一次性跑完十个模型，早上起来看结果。
对于想深入做 Agent 和长上下文应用的，CL-bench 的失败模式很有参考价值：模型不是不会推理，而是不会"把上下文当唯一事实来源"。你在做 RAG 或者文档问答时，可以在 system prompt 里强化这一点，比如明确要求"只依据提供的上下文回答，上下文未提及的内容一律回答不知道"。这个改动成本很低，但在 CL-bench 这类任务上往往能拉回几个百分点。
最后，如果你在配置过程中卡在通道或者 Key 的问题上，优先看接入文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面把 Base URL、Key、Model ID 三件套讲得比较清楚。需要新建 Key 就去 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。想先手动试一条消息确认模型行为，用模型对话页 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite 。长期跑批量评测的话，Coding Plan 页面 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 有对应的方案说明。配置跑通之后，剩下的就是耐心等全量结果落盘，然后对着分类别分数找短板。
