企业官网建设流程全解析

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 URL，ragas 的 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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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_KEY=sk-你的TaoToken密钥 TAOTOKEN_BASE_URL=https://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_key=TAOTOKEN_API_KEY, base_url=TAOTOKEN_BASE_URL, timeout=60.0, ) # Embedding 客户端（可复用同一个，这里分开便于单独调超时） embedding_client = OpenAI( api_key=TAOTOKEN_API_KEY, base_url=TAOTOKEN_BASE_URL, timeout=30.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, provider="openai", client=llm_client, ) # Embedding：同样走 OpenAI 兼容适配器 embeddings = embedding_factory( "openai", model=EMBEDDING_MODEL, client=embedding_client, )

如果你用的是 ragas 较新版本的指标集合 API（ragas.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, provider="openai", client=llm_client) embeddings = embedding_factory("openai", model=EMBEDDING_MODEL, client=embedding_client) metrics = [ ContextPrecision(llm=llm), AnswerCorrectness(llm=llm, embeddings=embeddings), ]

这里要强调一个对照关系，也就是常说的「三件套」：Base URL、Key、Model ID。在 TaoToken 场景下，Base URL 固定是https://taotoken.net/api，Key 是你控制台创建的sk-开头的字符串，Model ID 是你在模型列表里选定的对话模型和嵌入模型。这三样东西在 LLM client 和 embedding client 里都要出现，缺一不可。很多 401 报错就是因为 embedding client 忘了传api_key，或者base_url写成了官网带参数的链接。

如果你习惯用settings文件管理，也可以把上面的配置写成一个 TOML，然后用tomllib读取。不过对 ragas 来说，最终还是要落到 Python 对象上，所以直接用.env+config.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(llm=llm), ContextPrecision(llm=llm), ContextRecall(llm=llm), AnswerCorrectness(llm=llm, embeddings=embeddings), ] result = evaluate(dataset, metrics=metrics) print(result)

运行python verify_eval.py。如果链路正常，你会看到类似下面的输出（具体数值因模型而异）：

Evaluating: 100%|██████████| 4/4 [00:08<00: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( model=EMBEDDING_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，多了一层/v1，OpenAI 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 的散落，统一到一条通道之后，剩下的就是调指标和看数据了。