企业官网建设流程全解析

1. RAG 上线前，为什么评估比调参更值得先做

RAG 系统能跑通，和 RAG 系统能上线，中间隔着一整套评估。你大概率遇到过这种场景：向量库建好了，chunk 切了，Top-K 设成 5，随便问几个问题看着回答还行，于是准备接业务。结果真实用户一上来，问法千奇百怪，回答开始胡编，检索回来的上下文跟问题八竿子打不着，你根本不知道是检索的锅还是生成模型的锅。

RAG 性能评估要解决的就是这个「不知道哪坏了」的问题。它把整条链路拆成三个可测量的对象：用户 query、检索到的 context、模型生成的 response。这三者两两之间构成一组关系，也就是常说的 RAG Triad：context 和 query 之间的相关性衡量检索质量，response 和 context 之间的一致性衡量有没有幻觉，response 和 query 之间的相关性衡量有没有答非所问。三个分数一摆出来，问题定位就清楚了。

这套评估适合谁？适合已经搭出一个能跑的 RAG demo、准备往生产推的 LLM 应用开发者和算法工程师。你不需要先有标注团队，也不需要先买评估平台，用开源框架加一个统一的模型调用通道就能跑起来。我试过在本地用一套配置骨架把检索命中率、答案忠实度、上下文相关性这些指标一次性跑完，再拿结果反推是改 chunk 参数还是换 embedding 模型。

下面这篇会交付三样东西：一份可复制的评估配置文件骨架，一个本地验证脚本，以及如何通过 TaoToken 的统一 Key 和 API 通道接入评估用 LLM，完成一次端到端跑分和结果解读。评估用的模型调用全部走同一个入口，省得在多个平台的 Key 之间来回切换。

2. 评估前的前置准备：统一模型调用通道

评估 RAG 的时候，你会频繁调用 LLM 来做打分。RAGAS 这类框架默认走 OpenAI 的接口，但实际项目里你可能有自己的模型偏好，或者需要控制成本、控制调用稳定性。如果每个指标都单独配一套 Key 和 endpoint，配置文件会变得很难维护。

TaoToken 在这里的作用是提供一个统一的 API 通道。你申请一个 Key，拿到一个 base_url，之后不管是评估用的打分模型，还是被评估的 RAG 生成模型，都可以走同一个入口。对评估脚本来说，这意味着你只需要维护一份模型配置，换模型时改一个 model 名字就行。

先拿到 Key。打开官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，注册后在控制台里创建 API Key。控制台地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，Key 管理页面在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。创建完把 Key 复制出来，后面配置里要用。

API 的基础地址是 https://taotoken.net/api ，注意这个地址不带 UTM 参数，直接写进配置即可。它兼容 OpenAI 的接口格式，所以任何支持自定义 base_url 的框架都能接。评估脚本里我们会把它同时用作打分模型和 embedding 模型的入口。

如果你还没确定用哪个模型做评估，可以先去模型对话页面 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 手动问几个问题，感受一下不同模型的输出风格。评估打分对模型的指令遵循能力要求比较高，选一个稳定的就行，不必追求最强。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，遇到参数问题可以对照查。

注意：评估用的 Key 和线上业务用的 Key 建议分开管理，方便单独统计评估消耗，也避免评估脚本跑飞了影响线上额度。

3. 可复制的评估配置骨架与本地验证脚本

这一节是全文的核心。我会给出一份评估配置文件的骨架，包含检索命中率、答案忠实度、上下文相关性等指标项，然后配一个本地验证脚本，把配置读进来跑一次完整评估。

3.1 评估配置文件骨架

先建一个rag_eval_config.yaml，把模型通道、数据集路径、指标开关都放进去。这样换模型、换数据集不用改代码。

# rag_eval_config.yaml llm: provider: openai_compatible base_url: "https://taotoken.net/api" api_key: "${TAOTOKEN_API_KEY}" # 从环境变量读取，不要硬编码 model: "gpt-4o-mini" # 评估打分模型，可替换 temperature: 0.0 # 评估要稳定，温度设 0 embeddings: provider: openai_compatible base_url: "https://taotoken.net/api" api_key: "${TAOTOKEN_API_KEY}" model: "text-embedding-3-small" dataset: path: "./eval_dataset.jsonl" # 每行一条评估样本 fields: question: "question" answer: "answer" contexts: "contexts" ground_truth: "ground_truth" metrics: context_precision: true # 上下文精确度 context_recall: true # 上下文召回率 faithfulness: true # 忠实度 / Groundedness answer_relevancy: true # 答案相关性 context_relevancy: true # 上下文相关性 output: dir: "./eval_results" format: ["csv", "json"]

这份配置里，llm和embeddings都指向同一个 base_url，也就是 TaoToken 的 API 通道。评估框架会用它来调用打分模型和计算语义相似度。metrics段控制跑哪些指标，初期建议全开，跑几轮之后再按需裁剪。

数据集用 JSONL 格式，每行一条样本，结构长这样：

{"question": "RAG 的 chunk 大小怎么选？", "answer": "chunk 大小需要根据文档类型和检索粒度权衡，一般 256 到 512 token 是常见起点。", "contexts": ["chunk 大小影响检索召回精度...", "过大的 chunk 会引入噪声..."], "ground_truth": "chunk 大小没有固定最优值，通常从 256-512 token 开始调优。"}

contexts是检索回来的上下文列表，ground_truth是人工标注的标准答案。没有标注答案时，context_recall和context_precision会跳过，其余指标仍可计算。

3.2 本地验证脚本

接下来写run_eval.py，把配置读进来，构造数据集，调用评估框架跑分。

# run_eval.py import os import json import yaml from datasets import Dataset from langchain_openai import ChatOpenAI, OpenAIEmbeddings from ragas import evaluate from ragas.metrics import ( context_precision, context_recall, faithfulness, answer_relevancy, context_relevancy, ) from ragas.llms import LangchainLLM from ragas.embeddings import LangchainEmbeddings # 1. 读配置 with open("rag_eval_config.yaml", "r", encoding="utf-8") as f: cfg = yaml.safe_load(f) api_key = os.environ.get("TAOTOKEN_API_KEY") assert api_key, "请先设置 TAOTOKEN_API_KEY 环境变量" # 2. 构造评估用 LLM 和 Embedding，统一走 TaoToken 通道 eval_llm = ChatOpenAI( model=cfg["llm"]["model"], base_url=cfg["llm"]["base_url"], api_key=api_key, temperature=cfg["llm"]["temperature"], ) eval_emb = OpenAIEmbeddings( model=cfg["embeddings"]["model"], base_url=cfg["embeddings"]["base_url"], api_key=api_key, ) ragas_llm = LangchainLLM(eval_llm) ragas_emb = LangchainEmbeddings(eval_emb) # 3. 把自定义 LLM 绑定到各指标 faithfulness.llm = ragas_llm answer_relevancy.llm = ragas_llm answer_relevancy.embeddings = ragas_emb context_precision.llm = ragas_llm context_recall.llm = ragas_llm context_relevancy.llm = ragas_llm # 4. 读数据集 questions, answers, contexts, ground_truths = [], [], [], [] with open(cfg["dataset"]["path"], "r", encoding="utf-8") as f: for line in f: row = json.loads(line) questions.append(row["question"]) answers.append(row["answer"]) contexts.append(row["contexts"]) ground_truths.append(row.get("ground_truth", "")) evalsets = Dataset.from_dict({ "question": questions, "answer": answers, "contexts": contexts, "ground_truths": ground_truths, }) # 5. 选择指标并跑分 metric_map = { "context_precision": context_precision, "context_recall": context_recall, "faithfulness": faithfulness, "answer_relevancy": answer_relevancy, "context_relevancy": context_relevancy, } selected = [metric_map[k] for k, v in cfg["metrics"].items() if v] result = evaluate(evalsets, metrics=selected) df = result.to_pandas() # 6. 落盘 os.makedirs(cfg["output"]["dir"], exist_ok=True) df.to_csv(os.path.join(cfg["output"]["dir"], "scores.csv"), index=False) df.to_json(os.path.join(cfg["output"]["dir"], "scores.json"), orient="records", force_ascii=False) print(df[["question", "faithfulness", "answer_relevancy", "context_precision", "context_recall"]].head()) print("平均分：") print(df[["faithfulness", "answer_relevancy", "context_precision", "context_recall"]].mean())

跑之前装依赖：

pip install ragas datasets langchain-openai pyyaml pandas export TAOTOKEN_API_KEY="你的Key" python run_eval.py

脚本里最关键的一步是第 3 段，把ragas_llm和ragas_emb显式绑定到每个指标上。RAGAS 默认会去找 OpenAI 的环境变量，不绑定的话它会走默认通道，你的自定义配置就不生效了。绑定之后，所有打分请求都从 TaoToken 的 API 通道出去。

3.3 指标含义与解读口径

跑出分数之后，怎么读这些数字？下面这张表把每个指标的取值范围和低分含义列清楚。

一个实用的判断顺序：先看 Context Recall，召回不全后面全白搭；再看 Context Precision，召回对了但排得乱；然后看 Faithfulness，检索没问题但模型乱说；最后看 Answer Relevancy，前面都好但回答跑偏。按这个顺序排查，基本能定位到具体环节。

4. 端到端跑分与结果验证

配置和脚本都就位后，跑一次完整评估，确认通道和指标都正常工作。

4.1 准备一份小数据集

先用 10 到 20 条样本试跑，别一上来就上几百条。建一个eval_dataset.jsonl，每条样本包含 question、answer、contexts、ground_truth 四个字段。answer 是你当前 RAG 系统对 question 的真实输出，contexts 是系统实际检索回来的内容，ground_truth 是人工写的标准答案。

如果你手上还没有 RAG 系统的输出，可以先手动构造几条，验证评估链路能跑通。等链路确认没问题，再批量灌真实数据。

4.2 执行评估

export TAOTOKEN_API_KEY="你的Key" python run_eval.py

正常的话，终端会打印出每条样本的分数和整体平均分。输出类似：

question faithfulness answer_relevancy context_precision context_recall 0 RAG chunk 大小怎么选 0.92 0.88 0.75 0.80 1 RAG 评估指标有哪些 0.85 0.91 0.67 0.72 ... 平均分： faithfulness 0.885 answer_relevancy 0.895 context_precision 0.710 context_recall 0.760

同时eval_results/目录下会生成scores.csv和scores.json，方便后续做趋势对比。

4.3 结果解读示例

假设上面这组分数是你的真实结果。Faithfulness 0.885 和 Answer Relevancy 0.895 都不错，说明生成环节比较稳，模型基本在照着上下文回答，也没答非所问。但 Context Precision 只有 0.710，Context Recall 0.760，说明检索环节有提升空间。

Precision 偏低，意味着召回的 chunk 里混进了不相关的内容，或者相关 chunk 排名不够靠前。可以尝试加一个重排序步骤，或者把 Top-K 从 5 调到 3 看看 Precision 是否上升。Recall 偏低，说明有些该召回的知识没进来，可能是 chunk 切得太碎导致语义不完整，或者 embedding 模型对这类问题的语义匹配不够好。这两个指标往往需要一起调，调完重新跑一次评估，对比分数变化。

如果你想换一个评估模型再跑一遍，确认分数不是某个模型的主观偏好导致的，直接在配置里改llm.model就行，通道不用动。想快速对比不同模型对同一批数据的打分差异，可以去模型对话页面手动测几条，感受一下输出风格再决定。

5. 本篇常见错误排查

评估脚本跑不起来，多数是下面几个问题。我按出现频率排一下。

Key 没设置或设置错。脚本里读的是TAOTOKEN_API_KEY环境变量，如果你在配置文件里硬编码了 Key 但没设环境变量，会报认证失败。检查方式：echo $TAOTOKEN_API_KEY，确认有输出。另外注意 base_url 结尾不要多加/v1，TaoToken 的 API 地址是https://taotoken.net/api，框架会自动补路径。

RAGAS 没绑定自定义 LLM。这是最常见的坑。如果你只配了ChatOpenAI但没执行faithfulness.llm = ragas_llm这类绑定语句，RAGAS 会走它自己的默认通道，报 OpenAI Key 缺失。解决办法就是脚本第 3 段那几行绑定，一个指标都不能漏，尤其是answer_relevancy还要额外绑 embeddings。

数据集字段名对不上。RAGAS 要求 Dataset 的列名必须是question、answer、contexts、ground_truths。注意ground_truths是复数，而 JSONL 里我写的是ground_truth单数，脚本里做了映射。如果你直接改脚本，记得保持列名一致，否则会报 KeyError。

contexts 格式不对。contexts必须是字符串列表，每条样本对应一个列表。如果你传的是单个字符串，RAGAS 会按字符切分，分数会完全失真。检查你的 JSONL，contexts字段应该是["...", "..."]这种形式。

评估跑得特别慢或超时。每条样本要调用多次 LLM 打分，样本多了自然慢。先用 10 条试，确认没问题再扩。如果单条就超时，检查网络到taotoken.net的连通性，或者换一个响应更快的评估模型。评估脚本建议加个重试，网络抖动时不至于整批失败。

分数全是 NaN。通常是ground_truth为空导致context_recall和context_precision无法计算。如果你没有标注答案，就在配置里把这两个指标关掉，只跑 faithfulness 和 answer_relevancy。

提示：排查接入问题时，优先看接入文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，参数和错误码都有说明。Key 的问题去 API Keys 页面 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 确认状态。

6. 把评估接进你的开发流程

评估跑通一次不算完，真正有价值的是把它变成常规动作。每次改 chunk 参数、换 embedding 模型、调 prompt，都跑一遍同一份数据集，对比分数变化。这样你才能知道某个改动到底是让系统变好了还是变差了，而不是凭感觉。

具体做法：把eval_dataset.jsonl和rag_eval_config.yaml一起放进版本库，每次改动 RAG 配置就重新跑一次run_eval.py，把scores.csv按版本存档。跑上几轮之后，你会有一组可对比的历史数据，调参就有依据了。

如果你要长期做这类编码和评估任务，可以考虑用 Coding Plan https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，把评估脚本的开发、调试、迭代放在同一个通道里，省去反复配 Key 的麻烦。评估用的模型调用和日常编码共用一套凭证，管理起来更清爽。

最后给一个实操建议：评估数据集不要一次写太多，先覆盖你业务里最高频的 20 个问题类型，每个类型 2 到 3 条。这比堆 200 条随机问题更能反映真实短板。等这套小数据集跑稳了，再逐步扩充。评估这件事，先跑起来比跑得全更重要。