1. 本地跑 RAG 评测时密钥散落各处到底有多痛如果你正在按 ragas 官方文档中文版第五十八篇的节奏做 RAG 评测大概率已经踩过这个坑评测脚本里要配一个模型 Key生成答案的链路里要配一个嵌入模型可能又是另一套。跑一次evaluate()控制台报错先给你来个 401你翻半天发现是某个环境变量没导出。ragas 本身是个评测框架它不负责帮你管密钥它只负责把question、answer、contexts、ground_truth喂给指标然后算分。问题在于指标背后要调 LLM有的指标还要调 embedding这些调用最终都落到某个 endpoint 和某个 Key 上。我试过最乱的一次本地同时开着三个终端一个跑数据生成一个跑 ragas 评测一个跑嵌入向量化。三份.env文件三套 Base URL改一个模型名要同步改三个地方。更麻烦的是ragas 的llm_factory和embedding_factory对 provider 的识别逻辑不完全一样有时候你明明传了 client它还是去读默认环境变量结果就是「本地能跑、换台机器就挂」。这篇要解决的就是这件事把 ragas 评测链路里的模型 endpoint 与鉴权配置统一收敛到 TaoToken 的 API 通道上。你只需要维护一个 Key、一个 Base URLragas 的 LLM 调用和 embedding 调用都走同一条路。这样做的直接好处是评测脚本可以原样提交到仓库密钥通过环境变量注入换机器、换同事、换 CI 都不用改代码。适合谁看已经能跑通 ragas 基础evaluate()、但被多套密钥和 endpoint 折腾过的同学正在把 RAG 评测从 notebook 往工程化脚本迁移的同学以及想用 OpenAI 兼容接口统一管理多个模型来源的同学。下面从环境准备开始一步步给出可复制的配置片段最后用一个真实的评测请求验证链路是否打通。2. TaoToken 前置准备一个 Key 打通 ragas 的 LLM 与 Embedding在动手改 ragas 代码之前先把 TaoToken 这边的准备工作做完。核心就三件事拿到 API Key、确认 Base URL、选好模型 ID。这三样东西后面会同时出现在 ragas 的 LLM 配置和 embedding 配置里。先说 Base URL。TaoToken 的 API 入口是https://taotoken.net/api注意这个地址后面不加任何 UTM 参数它是给代码里base_url字段用的。官网入口是https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content这个带参数的链接是给人点进去注册和看文档用的别把它写进代码。很多同学第一次配的时候把带 UTM 的完整链接粘到base_url里结果请求路径变成了一堆查询参数拼接直接 404。然后是 API Key。登录之后进控制台在 API Keys 页面创建一个新的 Key。创建的时候建议按用途命名比如ragas-eval-local这样以后在用量页面能一眼看出是哪个项目在消耗。Key 只在创建时完整显示一次复制下来存到本地密码管理器或者直接写进.env别提交到 git。如果你还没创建过可以走这个路径先打开官网了解通道能力再进控制台创建 Key最后对照接入文档确认参数格式。模型 ID 这块要稍微注意。ragas 的指标分两类一类只需要 LLM比如Faithfulness、ContextPrecision、ContextRecall另一类还需要 embedding比如AnswerCorrectness、AnswerRelevancy、AnswerSimilarity。所以你在 TaoToken 这边至少要准备两个模型 ID一个对话模型用于 LLM 指标一个嵌入模型用于需要向量相似度的指标。对话模型可以选通用的指令模型嵌入模型选对应的 embedding 模型。具体有哪些可用在模型对话页面能直接看到列表也可以在那里先手动发一条消息确认通道正常。这里有个容易忽略的点ragas 的llm_factory在 provider 识别上有一套自动逻辑。如果你用 OpenAI 兼容的方式接入provider 传openai它会走 OpenAI 适配器这时候base_url和api_key都会被正确读取。如果你传google或者anthropic它会走对应的适配器那些适配器可能不认自定义base_url。所以统一到 TaoToken 的关键是让 ragas 走 OpenAI 兼容适配器把base_url指向 TaoToken 的 API 地址。这一点在后面的配置片段里会体现。最后提醒一下环境变量命名。ragas 和底层 SDK 会读一些约定俗成的变量名比如OPENAI_API_KEY、OPENAI_BASE_URL。为了避免和本机已有的其他项目冲突建议用带前缀的自定义变量比如TAOTOKEN_API_KEY、TAOTOKEN_BASE_URL然后在代码里显式传给 client。这样即使你机器上还跑着别的 OpenAI 项目也不会互相污染。3. 可复制配置环境变量、settings 片段与 ragas 初始化这一节是全文的核心给出可以直接复制粘贴的配置。分三层环境变量层、Python 配置层、ragas 初始化层。三层配合才能让 LLM 和 embedding 都走 TaoToken。先看环境变量。在项目根目录建一个.env文件内容如下# .env TAOTOKEN_API_KEYsk-你的TaoToken密钥 TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_LLM_MODEL你的对话模型ID TAOTOKEN_EMBEDDING_MODEL你的嵌入模型ID注意TAOTOKEN_BASE_URL结尾不要带斜杠也不要带任何查询参数。OpenAI SDK 在拼接路径时会自己处理/chat/completions和/embeddings你多写一个斜杠或者多带参数都会导致路径错误。.env文件记得加进.gitignore别让密钥进仓库。接下来是 Python 配置层。用python-dotenv加载环境变量然后创建两个 client一个给 LLM一个给 embedding。其实可以共用一个 client但分开写更清晰也方便你以后给 embedding 单独设超时。# config.py import os from dotenv import load_dotenv from openai import OpenAI load_dotenv() TAOTOKEN_API_KEY os.environ[TAOTOKEN_API_KEY] TAOTOKEN_BASE_URL os.environ[TAOTOKEN_BASE_URL] LLM_MODEL os.environ[TAOTOKEN_LLM_MODEL] EMBEDDING_MODEL os.environ[TAOTOKEN_EMBEDDING_MODEL] # LLM 客户端 llm_client OpenAI( api_keyTAOTOKEN_API_KEY, base_urlTAOTOKEN_BASE_URL, timeout60.0, ) # Embedding 客户端可复用同一个这里分开便于单独调超时 embedding_client OpenAI( api_keyTAOTOKEN_API_KEY, base_urlTAOTOKEN_BASE_URL, timeout30.0, )然后是 ragas 初始化层。这里的关键是llm_factory的provider参数传openai并且把上面创建的 client 传进去。embedding 用embedding_factory同样传openai和 client。# ragas_setup.py from ragas.llms import llm_factory from ragas.embeddings import embedding_factory from config import llm_client, embedding_client, LLM_MODEL, EMBEDDING_MODEL # LLM走 OpenAI 兼容适配器base_url 指向 TaoToken llm llm_factory( LLM_MODEL, provideropenai, clientllm_client, ) # Embedding同样走 OpenAI 兼容适配器 embeddings embedding_factory( openai, modelEMBEDDING_MODEL, clientembedding_client, )如果你用的是 ragas 较新版本的指标集合 APIragas.metrics.collections初始化方式略有不同但 client 的构造是一样的# ragas_collections_setup.py from ragas.llms import llm_factory from ragas.embeddings import embedding_factory from ragas.metrics.collections import AnswerCorrectness, ContextPrecision from config import llm_client, embedding_client, LLM_MODEL, EMBEDDING_MODEL llm llm_factory(LLM_MODEL, provideropenai, clientllm_client) embeddings embedding_factory(openai, modelEMBEDDING_MODEL, clientembedding_client) metrics [ ContextPrecision(llmllm), AnswerCorrectness(llmllm, embeddingsembeddings), ]这里要强调一个对照关系也就是常说的「三件套」Base URL、Key、Model ID。在 TaoToken 场景下Base URL 固定是https://taotoken.net/apiKey 是你控制台创建的sk-开头的字符串Model ID 是你在模型列表里选定的对话模型和嵌入模型。这三样东西在 LLM client 和 embedding client 里都要出现缺一不可。很多 401 报错就是因为 embedding client 忘了传api_key或者base_url写成了官网带参数的链接。如果你习惯用settings文件管理也可以把上面的配置写成一个 TOML然后用tomllib读取。不过对 ragas 来说最终还是要落到 Python 对象上所以直接用.envconfig.py的组合最省事。配置写完后先别急着跑评测下一节用一个最小请求验证链路。4. 验证请求跑一次最小评测确认指标正常返回配置写完最忌讳直接上全量数据集。先用一条样本验证链路确认 LLM 和 embedding 都能通再放大数据量。这一节给出一个最小可运行的评测脚本以及预期输出。先构造一条样本数据。ragas 的Dataset需要question、answer、contexts、ground_truth四个字段contexts是列表的列表。# verify_eval.py from datasets import Dataset from ragas import evaluate from ragas.metrics import ( Faithfulness, ContextPrecision, ContextRecall, AnswerCorrectness, ) from ragas_setup import llm, embeddings data { question: [法国的首都是哪里], answer: [法国的首都是巴黎。], contexts: [[法国位于西欧巴黎是其首都。]], ground_truth: [巴黎], } dataset Dataset.from_dict(data) metrics [ Faithfulness(llmllm), ContextPrecision(llmllm), ContextRecall(llmllm), AnswerCorrectness(llmllm, embeddingsembeddings), ] result evaluate(dataset, metricsmetrics) print(result)运行python verify_eval.py。如果链路正常你会看到类似下面的输出具体数值因模型而异Evaluating: 100%|██████████| 4/4 [00:0800:00, 2.1s/it] {faithfulness: 1.0000, context_precision: 1.0000, context_recall: 1.0000, answer_correctness: 0.9500}看到这个字典说明四件事都成了LLM 调用通了embedding 调用通了ragas 的指标计算逻辑跑完了结果能正常序列化。如果answer_correctness这一项报错而其他三项正常那基本可以定位到 embedding 配置有问题因为只有它需要向量。反过来如果四项全挂先查 LLM client 的base_url和api_key。再补一个更细的验证动作单独测一次 embedding 请求。有时候 ragas 的报错信息被包装过看不出根因直接调底层 client 更直观。# verify_embedding.py from config import embedding_client, EMBEDDING_MODEL resp embedding_client.embeddings.create( modelEMBEDDING_MODEL, input[测试嵌入通道], ) print(维度:, len(resp.data[0].embedding)) print(前三个值:, resp.data[0].embedding[:3])正常会打印出向量维度比如维度: 1536。如果这里报 401说明 Key 或 Base URL 有问题如果报 404说明模型 ID 写错了或者该模型不在你的可用列表里。这个脚本比跑完整评测快得多适合在改配置后第一时间验证。还有一个实用技巧在evaluate()外面包一层计时看看单条样本的耗时。RAG 评测的瓶颈通常在 LLM 调用次数上Faithfulness和ContextPrecision每个样本可能触发多次 LLM 请求。如果你发现单条样本要十几秒先别怀疑通道看看是不是指标选多了。验证阶段建议只留两三个指标确认通了再逐步加。5. 常见报错排查401、local proxy failed、reading choices 与 OAuth链路验证阶段最常见的几类报错这里逐个对照。每个报错都给出触发条件和排查路径你可以按顺序自查。401 Unauthorized。这是最高频的。触发条件通常是api_key为空、Key 写错、或者 Key 被禁用。排查顺序先确认.env里的TAOTOKEN_API_KEY确实被load_dotenv()加载了可以在config.py里print(TAOTOKEN_API_KEY[:8])看前几位再确认这个 Key 在控制台是启用状态最后确认base_url没有写成官网带参数的链接。注意401 有时也会因为base_url指向了错误的路径而出现比如你写成了https://taotoken.net/api/v1多了一层/v1OpenAI SDK 再拼/chat/completions就变成了/api/v1/chat/completions而实际路径可能不匹配。Base URL 就用https://taotoken.net/api别自己加版本号。local proxy failed / connection error。这类报错说明请求根本没发出去或者被本地网络环境拦了。排查顺序先确认本机能访问https://taotoken.net/api可以用curl -I https://taotoken.net/api看返回再检查是否有全局的HTTP_PROXY、HTTPS_PROXY环境变量被设置这些变量会被 OpenAI SDK 读取如果指向了一个不可用的本地端口就会报 proxy failed。可以在config.py里显式清掉os.environ.pop(HTTP_PROXY, None)和os.environ.pop(HTTPS_PROXY, None)。另外公司内网如果有出网限制也会表现为连接超时这种情况需要走内网允许的通道。reading choices / KeyError choices。这个报错通常出现在 ragas 解析 LLM 返回结果时。触发条件是返回的 JSON 结构里没有choices字段或者choices为空。可能的原因模型 ID 写成了 embedding 模型导致对话接口返回了嵌入结果或者请求被网关拦截返回了一个 HTML 错误页SDK 尝试按 JSON 解析失败。排查方法先用verify_embedding.py那种方式直接调llm_client.chat.completions.create()发一条你好打印完整resp看结构对不对。如果返回的是嵌入向量说明模型 ID 用错了把对话模型和嵌入模型对调一下。OAuth / authentication 相关报错。如果你之前用过某些需要 OAuth 流程的 SDK可能会在环境里留下 token 缓存文件ragas 或底层 SDK 误读了这些缓存。排查方法检查项目目录和用户主目录下有没有.credentials、token.json之类的文件临时移走再跑。另外如果你在代码里同时传了api_key和某个 OAuth 相关的 client 对象也可能冲突。统一用OpenAI(api_key..., base_url...)这一种方式别混用。指标返回 NaN 或 0。这不是报错但结果不对。常见原因是contexts为空列表或者ground_truth和answer完全不相关。ragas 的某些指标在上下文为空时会返回 0 或 NaN。排查时先打印dataset确认字段没丢再检查contexts是不是嵌套层级错了——它应该是[[文本1], [文本2]]这种列表的列表而不是[文本1, 文本2]。把这几类报错对照一遍基本能覆盖 90% 的接入问题。剩下的边缘情况建议直接看接入文档里的参数说明或者在模型对话页面手动发一条请求对比返回结构。6. 统一 Key 之后的评测工作流与 CTA配置收敛到 TaoToken 之后你的 ragas 评测工作流会变得清爽很多。原来散落在三个.env里的密钥现在只剩一份原来每个脚本开头都要重复的 client 构造现在抽到config.py里一次搞定。更重要的是评测脚本可以安全地提交到仓库密钥通过 CI 的环境变量注入本地和流水线用同一套代码。如果你要把评测跑成长期任务比如每次 RAG 应用发版都跑一遍回归建议把evaluate()的结果落盘成 JSON记录模型 ID、指标版本、数据集哈希。这样当指标波动时你能快速判断是模型换了、数据变了还是通道出了问题。TaoToken 的用量页面可以按 Key 查看调用量配合评测日志能定位到是哪次评测消耗突增。对于需要长期跑编码类 Agent 或批量评测的场景可以了解一下 Coding Plan它在高频调用下更划算。如果你只是想先验证模型通道是否满足评测需求直接去模型对话页面手动测几条比写脚本更快。创建 Key 和查看接入参数走控制台和接入文档这两个入口就够了。最后留一个实操建议把verify_eval.py和verify_embedding.py这两个脚本留在仓库里作为接入自检工具。每次换机器、换 Key、升级 ragas 版本之后先跑这两个脚本通过了再跑全量评测。这个习惯能帮你省下大量「以为是模型问题、其实是配置问题」的排查时间。评测链路本身不复杂复杂的是环境变量和 endpoint 的散落统一到一条通道之后剩下的就是调指标和看数据了。
ragas官方文档中文版（五十八）：用 TaoToken 统一 Key 跑通 RAG 评测链路
1. 本地跑 RAG 评测时密钥散落各处到底有多痛如果你正在按 ragas 官方文档中文版第五十八篇的节奏做 RAG 评测大概率已经踩过这个坑评测脚本里要配一个模型 Key生成答案的链路里要配一个嵌入模型可能又是另一套。跑一次evaluate()控制台报错先给你来个 401你翻半天发现是某个环境变量没导出。ragas 本身是个评测框架它不负责帮你管密钥它只负责把question、answer、contexts、ground_truth喂给指标然后算分。问题在于指标背后要调 LLM有的指标还要调 embedding这些调用最终都落到某个 endpoint 和某个 Key 上。我试过最乱的一次本地同时开着三个终端一个跑数据生成一个跑 ragas 评测一个跑嵌入向量化。三份.env文件三套 Base URL改一个模型名要同步改三个地方。更麻烦的是ragas 的llm_factory和embedding_factory对 provider 的识别逻辑不完全一样有时候你明明传了 client它还是去读默认环境变量结果就是「本地能跑、换台机器就挂」。这篇要解决的就是这件事把 ragas 评测链路里的模型 endpoint 与鉴权配置统一收敛到 TaoToken 的 API 通道上。你只需要维护一个 Key、一个 Base URLragas 的 LLM 调用和 embedding 调用都走同一条路。这样做的直接好处是评测脚本可以原样提交到仓库密钥通过环境变量注入换机器、换同事、换 CI 都不用改代码。适合谁看已经能跑通 ragas 基础evaluate()、但被多套密钥和 endpoint 折腾过的同学正在把 RAG 评测从 notebook 往工程化脚本迁移的同学以及想用 OpenAI 兼容接口统一管理多个模型来源的同学。下面从环境准备开始一步步给出可复制的配置片段最后用一个真实的评测请求验证链路是否打通。2. TaoToken 前置准备一个 Key 打通 ragas 的 LLM 与 Embedding在动手改 ragas 代码之前先把 TaoToken 这边的准备工作做完。核心就三件事拿到 API Key、确认 Base URL、选好模型 ID。这三样东西后面会同时出现在 ragas 的 LLM 配置和 embedding 配置里。先说 Base URL。TaoToken 的 API 入口是https://taotoken.net/api注意这个地址后面不加任何 UTM 参数它是给代码里base_url字段用的。官网入口是https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content这个带参数的链接是给人点进去注册和看文档用的别把它写进代码。很多同学第一次配的时候把带 UTM 的完整链接粘到base_url里结果请求路径变成了一堆查询参数拼接直接 404。然后是 API Key。登录之后进控制台在 API Keys 页面创建一个新的 Key。创建的时候建议按用途命名比如ragas-eval-local这样以后在用量页面能一眼看出是哪个项目在消耗。Key 只在创建时完整显示一次复制下来存到本地密码管理器或者直接写进.env别提交到 git。如果你还没创建过可以走这个路径先打开官网了解通道能力再进控制台创建 Key最后对照接入文档确认参数格式。模型 ID 这块要稍微注意。ragas 的指标分两类一类只需要 LLM比如Faithfulness、ContextPrecision、ContextRecall另一类还需要 embedding比如AnswerCorrectness、AnswerRelevancy、AnswerSimilarity。所以你在 TaoToken 这边至少要准备两个模型 ID一个对话模型用于 LLM 指标一个嵌入模型用于需要向量相似度的指标。对话模型可以选通用的指令模型嵌入模型选对应的 embedding 模型。具体有哪些可用在模型对话页面能直接看到列表也可以在那里先手动发一条消息确认通道正常。这里有个容易忽略的点ragas 的llm_factory在 provider 识别上有一套自动逻辑。如果你用 OpenAI 兼容的方式接入provider 传openai它会走 OpenAI 适配器这时候base_url和api_key都会被正确读取。如果你传google或者anthropic它会走对应的适配器那些适配器可能不认自定义base_url。所以统一到 TaoToken 的关键是让 ragas 走 OpenAI 兼容适配器把base_url指向 TaoToken 的 API 地址。这一点在后面的配置片段里会体现。最后提醒一下环境变量命名。ragas 和底层 SDK 会读一些约定俗成的变量名比如OPENAI_API_KEY、OPENAI_BASE_URL。为了避免和本机已有的其他项目冲突建议用带前缀的自定义变量比如TAOTOKEN_API_KEY、TAOTOKEN_BASE_URL然后在代码里显式传给 client。这样即使你机器上还跑着别的 OpenAI 项目也不会互相污染。3. 可复制配置环境变量、settings 片段与 ragas 初始化这一节是全文的核心给出可以直接复制粘贴的配置。分三层环境变量层、Python 配置层、ragas 初始化层。三层配合才能让 LLM 和 embedding 都走 TaoToken。先看环境变量。在项目根目录建一个.env文件内容如下# .env TAOTOKEN_API_KEYsk-你的TaoToken密钥 TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_LLM_MODEL你的对话模型ID TAOTOKEN_EMBEDDING_MODEL你的嵌入模型ID注意TAOTOKEN_BASE_URL结尾不要带斜杠也不要带任何查询参数。OpenAI SDK 在拼接路径时会自己处理/chat/completions和/embeddings你多写一个斜杠或者多带参数都会导致路径错误。.env文件记得加进.gitignore别让密钥进仓库。接下来是 Python 配置层。用python-dotenv加载环境变量然后创建两个 client一个给 LLM一个给 embedding。其实可以共用一个 client但分开写更清晰也方便你以后给 embedding 单独设超时。# config.py import os from dotenv import load_dotenv from openai import OpenAI load_dotenv() TAOTOKEN_API_KEY os.environ[TAOTOKEN_API_KEY] TAOTOKEN_BASE_URL os.environ[TAOTOKEN_BASE_URL] LLM_MODEL os.environ[TAOTOKEN_LLM_MODEL] EMBEDDING_MODEL os.environ[TAOTOKEN_EMBEDDING_MODEL] # LLM 客户端 llm_client OpenAI( api_keyTAOTOKEN_API_KEY, base_urlTAOTOKEN_BASE_URL, timeout60.0, ) # Embedding 客户端可复用同一个这里分开便于单独调超时 embedding_client OpenAI( api_keyTAOTOKEN_API_KEY, base_urlTAOTOKEN_BASE_URL, timeout30.0, )然后是 ragas 初始化层。这里的关键是llm_factory的provider参数传openai并且把上面创建的 client 传进去。embedding 用embedding_factory同样传openai和 client。# ragas_setup.py from ragas.llms import llm_factory from ragas.embeddings import embedding_factory from config import llm_client, embedding_client, LLM_MODEL, EMBEDDING_MODEL # LLM走 OpenAI 兼容适配器base_url 指向 TaoToken llm llm_factory( LLM_MODEL, provideropenai, clientllm_client, ) # Embedding同样走 OpenAI 兼容适配器 embeddings embedding_factory( openai, modelEMBEDDING_MODEL, clientembedding_client, )如果你用的是 ragas 较新版本的指标集合 APIragas.metrics.collections初始化方式略有不同但 client 的构造是一样的# ragas_collections_setup.py from ragas.llms import llm_factory from ragas.embeddings import embedding_factory from ragas.metrics.collections import AnswerCorrectness, ContextPrecision from config import llm_client, embedding_client, LLM_MODEL, EMBEDDING_MODEL llm llm_factory(LLM_MODEL, provideropenai, clientllm_client) embeddings embedding_factory(openai, modelEMBEDDING_MODEL, clientembedding_client) metrics [ ContextPrecision(llmllm), AnswerCorrectness(llmllm, embeddingsembeddings), ]这里要强调一个对照关系也就是常说的「三件套」Base URL、Key、Model ID。在 TaoToken 场景下Base URL 固定是https://taotoken.net/apiKey 是你控制台创建的sk-开头的字符串Model ID 是你在模型列表里选定的对话模型和嵌入模型。这三样东西在 LLM client 和 embedding client 里都要出现缺一不可。很多 401 报错就是因为 embedding client 忘了传api_key或者base_url写成了官网带参数的链接。如果你习惯用settings文件管理也可以把上面的配置写成一个 TOML然后用tomllib读取。不过对 ragas 来说最终还是要落到 Python 对象上所以直接用.envconfig.py的组合最省事。配置写完后先别急着跑评测下一节用一个最小请求验证链路。4. 验证请求跑一次最小评测确认指标正常返回配置写完最忌讳直接上全量数据集。先用一条样本验证链路确认 LLM 和 embedding 都能通再放大数据量。这一节给出一个最小可运行的评测脚本以及预期输出。先构造一条样本数据。ragas 的Dataset需要question、answer、contexts、ground_truth四个字段contexts是列表的列表。# verify_eval.py from datasets import Dataset from ragas import evaluate from ragas.metrics import ( Faithfulness, ContextPrecision, ContextRecall, AnswerCorrectness, ) from ragas_setup import llm, embeddings data { question: [法国的首都是哪里], answer: [法国的首都是巴黎。], contexts: [[法国位于西欧巴黎是其首都。]], ground_truth: [巴黎], } dataset Dataset.from_dict(data) metrics [ Faithfulness(llmllm), ContextPrecision(llmllm), ContextRecall(llmllm), AnswerCorrectness(llmllm, embeddingsembeddings), ] result evaluate(dataset, metricsmetrics) print(result)运行python verify_eval.py。如果链路正常你会看到类似下面的输出具体数值因模型而异Evaluating: 100%|██████████| 4/4 [00:0800:00, 2.1s/it] {faithfulness: 1.0000, context_precision: 1.0000, context_recall: 1.0000, answer_correctness: 0.9500}看到这个字典说明四件事都成了LLM 调用通了embedding 调用通了ragas 的指标计算逻辑跑完了结果能正常序列化。如果answer_correctness这一项报错而其他三项正常那基本可以定位到 embedding 配置有问题因为只有它需要向量。反过来如果四项全挂先查 LLM client 的base_url和api_key。再补一个更细的验证动作单独测一次 embedding 请求。有时候 ragas 的报错信息被包装过看不出根因直接调底层 client 更直观。# verify_embedding.py from config import embedding_client, EMBEDDING_MODEL resp embedding_client.embeddings.create( modelEMBEDDING_MODEL, input[测试嵌入通道], ) print(维度:, len(resp.data[0].embedding)) print(前三个值:, resp.data[0].embedding[:3])正常会打印出向量维度比如维度: 1536。如果这里报 401说明 Key 或 Base URL 有问题如果报 404说明模型 ID 写错了或者该模型不在你的可用列表里。这个脚本比跑完整评测快得多适合在改配置后第一时间验证。还有一个实用技巧在evaluate()外面包一层计时看看单条样本的耗时。RAG 评测的瓶颈通常在 LLM 调用次数上Faithfulness和ContextPrecision每个样本可能触发多次 LLM 请求。如果你发现单条样本要十几秒先别怀疑通道看看是不是指标选多了。验证阶段建议只留两三个指标确认通了再逐步加。5. 常见报错排查401、local proxy failed、reading choices 与 OAuth链路验证阶段最常见的几类报错这里逐个对照。每个报错都给出触发条件和排查路径你可以按顺序自查。401 Unauthorized。这是最高频的。触发条件通常是api_key为空、Key 写错、或者 Key 被禁用。排查顺序先确认.env里的TAOTOKEN_API_KEY确实被load_dotenv()加载了可以在config.py里print(TAOTOKEN_API_KEY[:8])看前几位再确认这个 Key 在控制台是启用状态最后确认base_url没有写成官网带参数的链接。注意401 有时也会因为base_url指向了错误的路径而出现比如你写成了https://taotoken.net/api/v1多了一层/v1OpenAI SDK 再拼/chat/completions就变成了/api/v1/chat/completions而实际路径可能不匹配。Base URL 就用https://taotoken.net/api别自己加版本号。local proxy failed / connection error。这类报错说明请求根本没发出去或者被本地网络环境拦了。排查顺序先确认本机能访问https://taotoken.net/api可以用curl -I https://taotoken.net/api看返回再检查是否有全局的HTTP_PROXY、HTTPS_PROXY环境变量被设置这些变量会被 OpenAI SDK 读取如果指向了一个不可用的本地端口就会报 proxy failed。可以在config.py里显式清掉os.environ.pop(HTTP_PROXY, None)和os.environ.pop(HTTPS_PROXY, None)。另外公司内网如果有出网限制也会表现为连接超时这种情况需要走内网允许的通道。reading choices / KeyError choices。这个报错通常出现在 ragas 解析 LLM 返回结果时。触发条件是返回的 JSON 结构里没有choices字段或者choices为空。可能的原因模型 ID 写成了 embedding 模型导致对话接口返回了嵌入结果或者请求被网关拦截返回了一个 HTML 错误页SDK 尝试按 JSON 解析失败。排查方法先用verify_embedding.py那种方式直接调llm_client.chat.completions.create()发一条你好打印完整resp看结构对不对。如果返回的是嵌入向量说明模型 ID 用错了把对话模型和嵌入模型对调一下。OAuth / authentication 相关报错。如果你之前用过某些需要 OAuth 流程的 SDK可能会在环境里留下 token 缓存文件ragas 或底层 SDK 误读了这些缓存。排查方法检查项目目录和用户主目录下有没有.credentials、token.json之类的文件临时移走再跑。另外如果你在代码里同时传了api_key和某个 OAuth 相关的 client 对象也可能冲突。统一用OpenAI(api_key..., base_url...)这一种方式别混用。指标返回 NaN 或 0。这不是报错但结果不对。常见原因是contexts为空列表或者ground_truth和answer完全不相关。ragas 的某些指标在上下文为空时会返回 0 或 NaN。排查时先打印dataset确认字段没丢再检查contexts是不是嵌套层级错了——它应该是[[文本1], [文本2]]这种列表的列表而不是[文本1, 文本2]。把这几类报错对照一遍基本能覆盖 90% 的接入问题。剩下的边缘情况建议直接看接入文档里的参数说明或者在模型对话页面手动发一条请求对比返回结构。6. 统一 Key 之后的评测工作流与 CTA配置收敛到 TaoToken 之后你的 ragas 评测工作流会变得清爽很多。原来散落在三个.env里的密钥现在只剩一份原来每个脚本开头都要重复的 client 构造现在抽到config.py里一次搞定。更重要的是评测脚本可以安全地提交到仓库密钥通过 CI 的环境变量注入本地和流水线用同一套代码。如果你要把评测跑成长期任务比如每次 RAG 应用发版都跑一遍回归建议把evaluate()的结果落盘成 JSON记录模型 ID、指标版本、数据集哈希。这样当指标波动时你能快速判断是模型换了、数据变了还是通道出了问题。TaoToken 的用量页面可以按 Key 查看调用量配合评测日志能定位到是哪次评测消耗突增。对于需要长期跑编码类 Agent 或批量评测的场景可以了解一下 Coding Plan它在高频调用下更划算。如果你只是想先验证模型通道是否满足评测需求直接去模型对话页面手动测几条比写脚本更快。创建 Key 和查看接入参数走控制台和接入文档这两个入口就够了。最后留一个实操建议把verify_eval.py和verify_embedding.py这两个脚本留在仓库里作为接入自检工具。每次换机器、换 Key、升级 ragas 版本之后先跑这两个脚本通过了再跑全量评测。这个习惯能帮你省下大量「以为是模型问题、其实是配置问题」的排查时间。评测链路本身不复杂复杂的是环境变量和 endpoint 的散落统一到一条通道之后剩下的就是调指标和看数据了。
