RAG Architect 是一个面向生产级 RAG（检索增强生成）流水线的设计、调优与评估技能，核心是三个确定性工具，要求用户针对真实语料和实际需求运行工具，而不是凭直觉选择分块大小或数据库。
用途 该技能用于在用户提出设计 RAG 流水线、选择分块策略或嵌入模型、挑选向量数据库、或评估检索质量等需求时提供系统化支持。
主要能力
- 语料分析与分块优化：通过 chunking_optimizer.py 对真实文档运行分析，输出 chunking.json，包含 corpus_info、各策略的 strategy_results、推荐策略及 sample_chunks。用户可依据 recommendation.strategy 及其配置，并查看 2-3 个 sample_chunks 来检查边界是否合理。
- 流水线设计：通过 rag_pipeline_designer.py 读取需求 JSON（必须包含 document_types[]、document_count、avg_document_size、queries_per_day、query_patterns[]、latency_requirement、budget_monthly、accuracy_priority、cost_priority、maintenance_complexity），输出 design.json，涵盖 chunking、embedding、vector_db、retrieval、reranking、evaluation、total_cost、architecture_diagram（mermaid）和 config_templates。
- 检索质量评估：通过 retrieval_evaluator.py 读取 queries.json 与 ground_truth.json，计算 precision@k、recall@k、MRR、NDCG@k，并输出 poor_precision_examples 与 poor_recall_examples 用于失败分析。
使用方式 所有路径相对于该技能文件夹，输出按“语料分析 → 设计 → 评估”链式衔接。 步骤一：python3 chunking_optimizer.py /path/to/docs --extensions .md .txt -o chunking.json 步骤二：编写需求 JSON 后运行 python3 rag_pipeline_designer.py requirements.json -o design.json 步骤三：准备 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 步骤四：验证循环。设计完成的判定条件是 eval.json 达到目标，典型下限为 precision@5 ≥ 0.8、recall@10 ≥ 0.85（需与用户按用例设定）。若低于目标，检查 poor-example 列表，每次只改变一个变量（分块策略→重跑步骤一；嵌入层级；增加重排；混合检索），再重跑步骤三，重复直至达标。
适用场景 适用于需要设计、调优或评估 RAG 检索流水线的工程场景，包括分块策略选择、嵌入模型层级选择、向量数据库选型、检索质量量化评估等。
限制与硬性规则
- 不得将模型名称或厂商价格作为当前事实呈现。嵌入模型与向量数据库定价可能在数月内失效。应推荐层级（Fast/self-hosted、Balanced open、Quality API、Code），给出当前代候选示例，并提示用户对照供应商实时定价页核实。
- 每个设计都必须以一次评估运行收尾。没有 retrieval_evaluator.py 数值的 RAG 设计只是假设，不是交付物。
- 分块必须由语料驱动，选择策略前必须对真实文档运行 chunking_optimizer.py。
- 成本模型应使用占位表（列：model | $/1M tokens (verify) | dims | as-of date），由用户填入实时数字；向量数据库（Pinecone/Weaviate/Qdrant/Chroma/pgvector）同理，选型标准（托管 vs 自托管、规模、过滤、现有 Postgres）是持久的，但金额不是。
- 交付物中每个推荐的模型/价格都需附带“核实当前定价/模型可用性”的说明及 as-of 日期。
参考资料 references/chunking_strategies_comparison.md（优化器实现的策略权衡）、references/embedding_model_benchmark.md（基准方法，含日期快照与过时警告）、references/rag_evaluation_framework.md（指标定义：faithfulness、relevance、precision/recall/NDCG）。