mcpField
R
rag-architect

rag-architect

github.com/alirezarezvani开发29.0k634 次安装1 天前更新
代码仓库

关于 rag-architect

RAG Architect 用于依据实际语料和需求设计、调优并评估 RAG 流水线。其工作流串联分块分析、流水线设计和检索评估，以实测结果指导方案，而非凭直觉选型。

主要功能

  1. 01针对文档语料优化分块
  2. 02按需求设计流水线
  3. 03使用排序指标评估检索
  4. 04检查低质量检索示例
  5. 05逐项调整流水线变量

适用场景

  1. 01为实际文档集选择分块策略
  2. 02根据工作负载规划 RAG 流水线
  3. 03依据真值数据衡量检索质量

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/alirezarezvani/claude-skills --skill rag-architect

安装后在 Claude Code 中输入/rag-architect确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

chunking_optimizer.py
rag_pipeline_designer.py
retrieval_evaluator.py
references/
chunking_strategies_comparison.md
embedding_model_benchmark.md
rag_evaluation_framework.md

详细介绍

RAG Architect

使用三个确定性工具设计、调优和评估生产级 RAG 流水线。请针对实际语料和需求运行这些工具，不要凭直觉选择分块大小或数据库。

硬性规则

  1. 切勿将模型名称或供应商价格当作当前事实呈现。 嵌入模型和向量数据库定价会在数月内过时。请推荐一个等级（见下表），给出一个当前代际的候选模型，并告知用户以服务商的实时定价页面为准进行核实。
  2. 每个设计都必须以一次评估运行结束。 没有 retrieval_evaluator.py 数据的 RAG 设计只是假设，不是交付物。
  3. 分块必须以语料为依据。 在选择策略之前，先对真实文档运行 chunking_optimizer.py。

嵌入模型等级（模式，而非价格表）

等级当前代际示例（使用前请核实）适用场景
快速 / 可自托管all-MiniLM-L6-v2、bge-small对成本敏感、规模小、实时场景
均衡开源all-mpnet-base-v2、bge-large、e5-large在不依赖 API 的前提下兼顾质量
高质量 APItext-embedding-3-large、voyage-3-large以准确率优先的通用检索
代码voyage-code-3、CodeBERT 系列代码搜索语料

定价规范： 使用占位表构建成本模型，列为 model | $/1M tokens (verify) | dims | as-of date，并由用户填入实时数字。向量数据库（Pinecone/Weaviate/Qdrant/Chroma/pgvector）同理：选型标准（托管还是自托管、规模、过滤能力、现有 Postgres）具有长期参考价值，而具体的美元数字则不然。

工作流

所有路径均相对于本技能文件夹。输出环环相扣：语料分析 → 设计 → 评估。

1. 分析语料并选择分块方式
python3 chunking_optimizer.py /path/to/docs --extensions .md .txt -o chunking.json

输出 chunking.json，包含 corpus_info、各策略的 strategy_results、recommendation 以及 sample_chunks。使用 recommendation.strategy 及其配置；向用户展示 2-3 个 sample_chunks，以便其检查分块边界是否合理。

2. 根据需求设计流水线

编写一个需求 JSON，包含以下键（全部为必填）：document_types[]、document_count、avg_document_size（字符数）、queries_per_day、query_patterns[]、latency_requirement、budget_monthly、accuracy_priority（0-1）、cost_priority（0-1）、maintenance_complexity。

python3 rag_pipeline_designer.py requirements.json -o design.json

输出 design.json，包含 chunking、embedding、vector_db、retrieval、reranking、evaluation、total_cost、architecture_diagram（mermaid）以及 config_templates。展示该架构图；并将每个 cost_monthly 数值标注为需核实的估算值（规则 1）。

3. 评估检索质量

准备 queries.json（{id, text} 列表或 {"queries": [...]}）和 ground_truth.json（{query_id: [relevant_doc_ids]}），然后运行：

python3 retrieval_evaluator.py queries.json /path/to/docs ground_truth.json --k-values 3 5 10 -o eval.json

输出 precision@k、recall@k、MRR、NDCG@k，以及用于失败分析的 poor_precision_examples / poor_recall_examples。

4. 验证循环

只有满足以下条件，设计才算完成：

  1. eval.json 达到目标——典型下限：precision@5 ≥ 0.8，recall@10 ≥ 0.85（需与用户按具体用例确定）。
  2. 若未达标：检查失败示例列表，然后只改变一个变量（分块策略 → 重新运行步骤 1；嵌入模型等级；增加重排序；混合检索），再重新运行步骤 3。如此反复。
  3. 交付物中推荐的每个模型或价格都须附带“核实当前定价/模型可用性”的说明，并注明截止日期。

参考资料

  • references/chunking_strategies_comparison.md — 优化器所实现的分块策略权衡
  • references/embedding_model_benchmark.md — 基准测试方法论（带日期的快照；文首有时效性警告）
  • references/rag_evaluation_framework.md — 指标定义（忠实度、相关性、precision/recall/NDCG）

评论

支持 Markdown