1. RAG 检索效果差先别急着换模型RAG检索增强生成说白了就是让大模型先翻资料再答题检索环节翻错了页后面生成再强也白搭。我见过太多团队一发现答不准第一反应就是换更大的模型、换更贵的 embedding结果折腾两周准确率原地踏步。问题往往出在检索链路的某一层而不是模型本身。这篇面向已经用统一 Key 接入多模型的开发者聚焦 embedding 召回与 reranker 精排这两层最容易拖垮效果的环节给出一套可复制的五层诊断法从数据、向量、检索、重排到生成逐层定位配合 config.toml 与 settings.json 骨架、固定 query 对比召回率与重排得分的验证动作帮你判断到底是向量化、索引还是重排环节出了问题。适合谁正在做企业知识库问答、文档检索、Agent 记忆召回且已经能跑通基础 RAG 但效果不达标的开发者。整套流程不需要你重写业务代码只需要在配置层做对照实验。2. TaoToken 前置准备统一 Key 接入多模型诊断 RAG 效果差核心动作是做对照实验——同一批 query换不同 embedding、换不同 reranker看召回率和重排得分怎么变。如果每个模型都要单独申请 Key、单独配环境变量实验成本会高到让你放弃。TaoToken 的价值就在这里一个 Key 覆盖多家模型切换模型只改配置不改代码特别适合做这种逐层排查。你需要准备的东西不多一个 TaoToken API Key在控制台的 API Keys 页面创建地址是 https://taotoken.net/api-keys确认你的调用基址用 https://taotoken.net/api 注意这个地址不带任何查询参数一个能跑 Python 的环境装好 openai、numpy、rank_bm25 这几个包创建 Key 之后把它写进环境变量别硬编码在代码里export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api注意基址只写到 /api 这一层SDK 会自动拼接 /v1/chat/completions 之类的路径。如果你手动拼了 /v1反而会 404。模型对话的在线调试入口在 https://taotoken.net/model-chat 你可以先在网页上确认某个 embedding 或 reranker 模型能不能正常返回再去写代码省得在脚本里反复试错。接入文档在 https://taotoken.net/doc 里面有各模型的参数说明和返回格式排查返回结构对不上的问题时很有用。3. 可复制配置config.toml 与 settings.json 骨架诊断要可复现配置就得外置。下面这份 config.toml 把五层里跟检索相关的参数全暴露出来方便你逐项改、逐项测。# config.toml —— RAG 五层诊断配置骨架 [api] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY timeout 60 max_retries 3 [embedding] # 诊断时在这里切换模型观察召回率变化 model bge-large-zh batch_size 32 normalize true dimension 1024 [index] # 索引类型flat / ivf_flat / hnsw type hnsw metric cosine hnsw_m 32 hnsw_ef_construction 200 hnsw_ef_search 64 [retrieval] top_k 20 score_threshold 0.35 hybrid_enabled true vector_weight 0.6 bm25_weight 0.4 [rerank] enabled true model bge-reranker-large candidate_k 50 score_threshold -2.0 final_k 5 [generation] model gpt-4o-mini temperature 0.1 max_context_chunks 5 reorder_context true对应的 settings.json 用于运行时覆盖方便你做 A/B 对照不用改 toml{ experiment_name: rerank_on_vs_off, embedding_model: bge-large-zh, rerank_enabled: true, retrieval: { top_k: 20, score_threshold: 0.35 }, rerank: { candidate_k: 50, final_k: 5 }, eval: { query_file: eval_queries.jsonl, metrics: [hit1, hit3, hit5, mrr] } }加载逻辑很简单toml 做默认值json 做实验覆盖import json import tomllib from pathlib import Path def load_config(toml_pathconfig.toml, json_pathsettings.json): with open(toml_path, rb) as f: cfg tomllib.load(f) if Path(json_path).exists(): with open(json_path, r, encodingutf-8) as f: override json.load(f) cfg deep_merge(cfg, override) return cfg def deep_merge(base, override): for k, v in override.items(): if isinstance(v, dict) and isinstance(base.get(k), dict): base[k] deep_merge(base[k], v) else: base[k] v return base这样你每次只改 settings.json 里的一个字段就能跑一轮对照实验记录也干净。4. 逐层诊断清单与验证请求4.1 数据层先看切块和脏数据数据层的问题最隐蔽也最致命。扫描件 OCR 的错字、PPT 转出来的占位符、重复段落进了向量库就是噪声。诊断动作随机抽 50 个 chunk人工看有没有半截句子、模板文字、乱码。如果通过率低于 80%先洗数据再谈调参。切块策略上固定字符数切块经常把一段完整说明切成两半检索出来只有半截大模型自然答不对。改成按标题层级优先、段落其次、字符数兜底。4.2 向量层embedding 模型对照固定一批 query换 embedding 模型跑召回看 Hit1 和 MRR。通用模型在专业领域经常不如领域微调过的小模型。用下面的脚本跑对照import os import numpy as np from openai import OpenAI client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], ) def embed(texts, model): resp client.embeddings.create( modelmodel, inputtexts, ) return np.array([d.embedding for d in resp.data]) def hit_at_k(query_vec, doc_vecs, gold_idx, k): sims doc_vecs query_vec topk np.argsort(-sims)[:k] return 1.0 if gold_idx in topk else 0.0 def mrr(query_vec, doc_vecs, gold_idx): sims doc_vecs query_vec rank int(np.where(np.argsort(-sims) gold_idx)[0][0]) 1 return 1.0 / rank把候选模型比如 bge-large-zh、m3e-base、某个通用大厂模型都跑一遍记录 Hit1、Hit3、Hit5、MRR 和延迟。哪个模型在你的数据上 Hit1 最高就用哪个别迷信品牌。4.3 检索层混合检索与阈值纯向量检索对精确关键词不敏感搜「错误码 502」可能把「错误码 503」也召回。加一路 BM25 做关键词匹配两路分数归一化后加权融合from rank_bm25 import BM25Okapi def tokenize(text): tokens [] for c in text: if \u4e00 c \u9fff: tokens.append(c) elif c.isascii() and c.isalnum(): tokens.append(c.lower()) return tokens def hybrid_search(query, vector_store, docs, top_k20, vw0.6, bw0.4): vec_res vector_store.similarity_search(query, ktop_k * 3) vec_scores {r.metadata[doc_id]: r.score for r in vec_res} bm25 BM25Okapi([tokenize(d) for d in docs]) bm_scores bm25.get_scores(tokenize(query)) bm_dict {fdoc_{i}: s for i, s in enumerate(bm_scores)} vn normalize(vec_scores) bn normalize(bm_dict) fused {} for did in set(vn) | set(bn): fused[did] vw * vn.get(did, 0.0) bw * bn.get(did, 0.0) ranked sorted(fused.items(), keylambda x: -x[1]) return ranked[:top_k]同时把固定 top-k 改成阈值过滤只返回相似度高于 score_threshold 的结果最多不超过 top_k。宁可少返回也别把不相关文档硬塞给大模型。4.4 重排层reranker 候选数与阈值重排是最后一公里。向量检索是粗筛reranker 做精排。关键参数有两个候选数 candidate_k 和分数阈值 score_threshold。def rerank(query, candidates, modelbge-reranker-large, threshold-2.0, final_k5): pairs [(query, c[text]) for c in candidates] resp client.post( /v1/rerank, json{model: model, query: query, documents: [p[1] for p in pairs]}, ) scored sorted(resp[results], keylambda x: -x[relevance_score]) kept [s for s in scored if s[relevance_score] threshold] return kept[:final_k]候选数太少比如只传 10 个reranker 没得挑效果出不来建议 candidate_k 设 50 左右。阈值设太低会把不相关文档放进来设太高会漏掉正确答案需要在你自己的测试集上扫一遍找平衡点。4.5 生成层上下文顺序与 prompt检索对了不代表答得对。大模型对上下文中间位置的信息利用效率最低最相关的 chunk 要放第 1 位第二相关的放最后其余倒序放中间def reorder_context(docs): if len(docs) 2: return docs return [docs[0]] list(reversed(docs[1:-1])) [docs[-1]]prompt 里明确写只能用给定上下文、不要编造、找不到就说不知道。规则写具体别给大模型自由发挥的空间。5. 本篇常见错排查报错 401 UnauthorizedKey 没读到。检查环境变量名是否和 config.toml 里的 api_key_env 一致别把 Key 写死在代码里又忘了 export。报错 404 Not Found基址拼错。base_url 只写到 https://taotoken.net/api 不要手动加 /v1SDK 会自己拼。embedding 维度对不上换了 embedding 模型但没重建索引。不同模型维度不同换模型必须重新向量化并重建索引否则检索结果全是乱的。reranker 返回空candidate_k 设太小或者阈值设太高把所有结果都过滤了。先把阈值调到 -10 看有没有返回再逐步往上调。召回率正常但答案还是错问题在生成层。检查上下文顺序有没有优化、prompt 有没有约束、max_context_chunks 是不是塞太多导致中间信息被忽略。混合检索后效果反而降了vector_weight 和 bm25_weight 没调好。纯向量和纯 BM25 各跑一遍确认两路单独都正常再调权重。延迟突然变高索引类型选错。小数据量用 flat 没问题10 万条以上建议 hnswef_search 别设太大。6. 下一步把诊断跑成习惯排查 RAG 效果差最怕的就是凭感觉换模型。建一个 50 条的固定测试集每次只改一个变量记录 Hit1、Hit3、MRR 和延迟。改完 embedding 跑一轮改完 reranker 跑一轮改完阈值再跑一轮。三周下来你会对每一层的贡献有清晰认知而不是在黑暗里乱撞。如果你要长期做编码类或 Agent 类应用反复调模型和参数会很频繁可以考虑 Coding Plan地址是 https://taotoken.net/coding-plan 统一 Key 下切换模型做对照实验会省很多事。接入细节和返回格式对不上时翻一下接入文档 https://taotoken.net/doc 大部分坑里面都有说明。模型对话的在线验证入口在 https://taotoken.net/model-chat 改完配置先在那儿确认模型通不通再跑批量脚本。
