agentic-rag

一个面向本地文档知识库的单用户 Agentic RAG 原型项目，当前版本重点验证：

• 本地 Markdown / TXT / PDF 文档导入
• 图文结构保留与正文图文混排回答
• 混合检索（BM25 + Vector + RRF + 可开关 rerank）
• 基于 LangGraph 的单 agent 检索闭环
• Streamlit 聊天界面、引用展示与调试轨迹

当前能力概览

• 001 多模态导入
  • 解析 PDF / Markdown / TXT
  • 保留文本块与图片块
  • 生成图片说明并组装 chunk
• 002 混合检索
  • 关键词召回、向量召回、融合与重排
  • 本地索引持久化与手测入口
• 003 单 agent 编排
  • LangGraph 驱动的 agent loop
  • metadata_tool、retrieve_evidence、evaluate、final_answer
• 004 Streamlit UI
  • 正文图文混排
  • 默认折叠 citations 与 Debug Trace 展示

Agent Loop

系统的核心问答链路是一个基于 LangGraph 的单 agent 检索闭环，不是“单次检索 + 单次回答”的薄封装。它负责先判断问题类型，再决定走元数据定位还是正文证据检索，必要时继续观察证据并追加检索，最后再收束为最终回答。

flowchart TD
    A[用户问题] --> B[classify]
    B -->|metadata| C[metadata_tool]
    B -->|content| D[retrieve_evidence]
    B -->|mixed| C
    C --> E[evaluate]
    D --> E
    E -->|metadata_then_retrieve| C
    E -->|retrieve_again| D
    E -->|finalize / metadata_only| F[final_answer]
    F --> G[answer_text]
    F --> H[rich_blocks]
    F --> I[citations / trace]

Loading

主流程固定为：

1. classify 将问题分为 metadata、content 或 mixed
2. metadata_tool 或 retrieve_evidence 定位类问题优先走 metadata_tool，内容类问题优先走 retrieve_evidence
3. evaluate 基于当前证据判断是否已足够回答，还是需要改写 query 继续检索
4. final_answer 基于命中的证据与候选图片生成最终回答

这条 loop 的关键约束是：

• metadata_tool 只负责结构化定位和过滤，不负责正文证据检索
• retrieve_evidence 封装了 hybrid retrieval、融合与重排
• evaluate 决定继续检索还是收束回答
• final_answer 必须基于命中证据生成回答，而不是只返回模板文案

继续阅读：

• 架构文档
• 003 spec

图文混排策略

图文混排不是 UI 事后“补几张图”，而是 final_answer 生成链路的一部分。系统先从命中的 chunk 中整理出候选图片，再把这些候选图片交给回答生成阶段；模型在正文中通过图片占位符决定是否插图以及插图位置，系统再将其解析为 rich_blocks，最后由 Streamlit 按顺序渲染。

flowchart TD
    A[retrieval hits] --> B[整理 candidate_images]
    A --> C[整理 evidence_hits]
    B --> D[answer generation]
    C --> D
    D --> E[输出 answer_markdown]
    E --> F["包含 [[IMAGE:image_key]] 占位符"]
    F --> G[占位符解析器]
    G --> H[text blocks]
    G --> I[image blocks]
    H --> J[rich_blocks]
    I --> J
    J --> K[Streamlit 按顺序渲染]

Loading

高层流程如下：

1. 检索命中正文 chunk 与关联图片
2. final_answer 整理候选图片与图片标识
3. 回答生成阶段输出带 [[IMAGE:image_key]] 占位符的正文
4. 系统将占位符解析为 rich_blocks
5. UI 按 rich_blocks 顺序渲染文本块与图片块

这条策略的关键约束是：

• 图片只能来自本轮命中的候选图片，模型不能虚构图片
• 图片在正文中的位置由回答生成结果决定，不由 UI 事后重排
• 图片展示优先使用原始 caption，不直接展示检索用长描述
• citations 与 debug trace 属于附加信息，不参与正文图文混排

继续阅读：

• 003 spec
• 004 spec

系统架构总览

主链路按 feature 分层推进：

1. 001 ingestion 文档解析、清洗、图片导出、chunk 组装
2. 002 hybrid retrieval 索引构建、关键词召回、向量召回、融合与重排
3. 003 orchestration 单 agent 决策、检索闭环、最终回答与图片占位符解析
4. 004 ui 将 003 的结构化回答渲染为聊天界面

更详细的设计请看：

• 架构文档
• 技术决策
• 术语表

核心模块分层

• src/agentic_rag/ingestion/：解析、清洗、切块与图片处理
• src/agentic_rag/retrieval/：索引、召回、融合、重排
• src/agentic_rag/agents/：分类、评估、图式编排、手测入口
• src/agentic_rag/services/：用例编排与最终回答组装
• src/agentic_rag/app/：Streamlit 页面、页面状态与 UI 适配
• src/agentic_rag/llm/：OpenAI 兼容模型接口适配
• src/agentic_rag/schemas/：结构化输入输出类型

本地运行与手动演示

环境准备

uv sync

质量门禁

uv run ruff check .
uv run ruff format --check .
uv run pyright
uv run pytest -q

Feature 001：手动验证导入链路

uv run scripts/ingest.py \
  --pdf tests/fixtures/pdfs/1706.03762v7.pdf

Feature 001 + 002：手动验证检索链路

uv run scripts/retrieve.py \
  --pdf tests/fixtures/pdfs/1706.03762v7.pdf \
  --query "attention architecture"

Feature 003：手动验证单 agent 编排

uv run scripts/orchestrate.py \
  --query "attention architecture"

仅验证编排逻辑时可使用：

uv run scripts/orchestrate.py \
  --query "attention architecture" \
  --heuristic

Feature 004：启动 Streamlit UI

uv run streamlit run src/agentic_rag/app/streamlit_app.py

接口连通性排查

uv run scripts/check_chat_api.py

开发工作流

开始任何实现前，先阅读：

• AGENTS.md
• 对应 feature 的 spec.md
• 对应 feature 的 tasks.md
• 对应 feature 的 acceptance.md

推荐节奏：

1. 明确当前目标 feature
2. 只处理 tasks.md 中未完成的内容
3. 先补失败测试
4. 实现最小代码
5. 跑质量门禁
6. 更新任务状态与验收文档

与 Codex 协作时，优先复用：

• start-feature.md
• continue-feature.md
• review-feature.md
• revise-spec.md

目录说明

• docs/：长期文档、决策记录、协作提示模板
• specs/：000~004 feature 规格
• src/agentic_rag/：产品代码
• tests/：单元、集成、端到端测试与夹具
• scripts/：本地开发、联调与演示脚本
• data/：本地知识库与索引目录
• templates/python-ai-starter/：从本项目抽出的通用 Python-AI vibe coding 骨架

环境变量

复制 .env.example 并按实际环境填写：

• OPENAI_BASE_URL
• OPENAI_API_KEY
• CHAT_MODEL
• VLM_MODEL
• EMBEDDING_MODEL
• RERANK_MODEL
• KNOWLEDGE_BASE_PATH
• INDEX_STORAGE_PATH
• TOP_K
• KEYWORD_TOP_K
• VECTOR_TOP_K
• RERANK_TOP_N
• RERANK_ENABLED

当前边界与已知限制

• 当前定位是单用户、本机优先原型，不做多用户权限与分布式部署
• metadata_tool 是轻量结构化定位工具，不是完整元数据搜索引擎
• 当前模板目录是“可独立拷走的 starter repo 骨架”，还没有单独拆成外部仓库

通用模板

如果你想把这套 vibe coding 骨架复用于其他项目，请参考：

• templates/python-ai-starter

它保留了：

• 仓库级 AGENTS.md
• docs/prompts/
• spec/tasks/acceptance 模板
• Python 工程基线
• 一个最小示例 feature