从零开始做一个 AI Agent以 Java Web RAG 学习助手为例本文是一套面向技术博客专栏的完整教程。它不是只讲概念而是以当前项目为真实案例从一个最小后端 API 出发逐步扩展到课程资料知识库、RAG 问答、轻量级 Agent Harness、工具注册表、执行 Trace、答案校验、学习记忆和前端工作台。示例项目定位面向 Java Web 课程资料的 RAG Agent 学习助手用户可以上传课程课件、实验指导书、代码文件和配置文件。系统会解析资料、切块、建立检索索引用户提交学习任务后Agent 会判断任务类型、规划步骤、调用工具、生成回答、校验引用并把执行过程展示给前端。专栏总目录项目总览从普通问答到课程学习 Agent技术栈和工程结构FastAPI、Vue、SQLite、RAG、Agent Harness后端基础设施配置、数据库、模型和 Schema资料上传文件存储、文档记录和重建索引文档解析PDF、Word、PPT、Markdown、代码文件如何进入系统文本切块chunk、metadata、语义类型和 embedding 状态检索系统关键词检索、向量检索、query rewrite 和 rerankLLM 与 Embedding Providerstub、OpenAI-compatible API 和本地模型接入Chat 问答入口兼容普通问答同时接入 Agent 主链路Agent Harness一次 Agent run 的生命周期Planner、Executor 与 Tool RegistryAgent 如何规划和调用工具Agent 校验、安全边界与资料不足处理Agent 记忆短期上下文、长期学习画像和推荐下一步前端工作台资料管理、Agent 任务、Trace、历史和健康状态测试、局限和演进从教学项目走向生产级 Agent SaaS第 7 篇检索系统关键词检索、向量检索、query rewrite 和 rerank7.1 检索入口文件backend/app/services/retrieval.py核心函数defretrieve_chunks(question:str,top_k:int5)-list[RetrievedChunk]:整体流程question - rewrite_retrieval_queries - keyword scoring - vector search - merge ranked chunks - rerank_chunks_with_llm - top_k7.2 RetrievedChunk检索结果使用RetrievedChunk包含chunk_id document_id content source_title source_path source_page language score retrieval_sourceretrieval_source用于区分keyword vector7.3 中文和代码友好的 tokenizetoken 规则TOKEN_REre.compile(r[A-Za-z0-9_]|[\u4e00-\u9fff],re.UNICODE)它能同时处理LoginServlet doPost web.xml Servlet 生命周期 登录流程中文会拆成单字和 bigram英文和代码标识符会转小写。7.4 LLM query rewriterewrite_retrieval_queries会把原始问题改写为更适合检索的查询。例如原问题登录功能为什么跳转失败 可能改写 1. 登录 跳转 失败 2. LoginServlet doPost redirect 3. web.xml servlet mapping 4. session login error如果 LLM 不可用就返回原始问题作为 fallback。7.5 关键词检索关键词检索会对每个 chunk 计算 overlapquery tokens vs content tokens source_path tokens metadata tokens得分len(overlap) / sqrt(content_token_count)这个公式避免长文本天然得分过高。7.6 向量检索文件backend/app/services/vector_store.py向量检索流程问题 - embedding - 遍历已 embedded chunks - cosine_similarity - 按分数排序当前向量存在 SQLite 的 JSON 字段里。按照路线B实现这适合教学和小规模 MVP不适合大规模生产。路线 A专用向量库pgvector / Milvus / ChromaPostgreSQL pgvector专门加了 vector 类型字段数据库原生支持向量相似度计算余弦、欧氏距离SQL 里直接 ORDER BY embedding - ‘[…]’ 做检索数据库底层优化向量索引适合百万级以上向量。向量 元数据统一持久化数据库层内置向量索引与相似度计算。路线 BSQLite 存 JSON 向量SQLite JSON 方案是全量拉取向量到 Python 内存代码里手动算相似度检索逻辑全在 Python 代码全量 / 过滤后取出所有向量loads 转数组numpy 手动算余弦相似度路线 CFAISS 向量检索库内存索引配套外部数据库存业务数据代表faiss搭配 SQLite/PostgreSQL 做元数据存储核心特点只做高速向量计算不负责持久化、不存业务元数据。小规模 demoSQLite / Numpy中等 RAG 应用Chroma大规模高性能向量检索FAISS / Milvus / Qdrant7.7 LLM rerank混合检索后会把候选 chunk 交给 LLM rerankquestion candidates - LLM 返回 chunk_ids 顺序如果 LLM 不可用或返回无效 JSON就使用原始排序。7.8 为什么这个检索设计适合课程 Agent课程资料同时包含自然语言和代码。纯向量检索可能漏掉精确类名纯关键词检索又不理解语义。混合检索能同时照顾课程概念 实验步骤 代码文件 配置文件 报错信息 复习题线索
从零开始做一个AI Agent（七）检索系统：关键词检索、向量检索、query rewrite 和 rerank
从零开始做一个 AI Agent以 Java Web RAG 学习助手为例本文是一套面向技术博客专栏的完整教程。它不是只讲概念而是以当前项目为真实案例从一个最小后端 API 出发逐步扩展到课程资料知识库、RAG 问答、轻量级 Agent Harness、工具注册表、执行 Trace、答案校验、学习记忆和前端工作台。示例项目定位面向 Java Web 课程资料的 RAG Agent 学习助手用户可以上传课程课件、实验指导书、代码文件和配置文件。系统会解析资料、切块、建立检索索引用户提交学习任务后Agent 会判断任务类型、规划步骤、调用工具、生成回答、校验引用并把执行过程展示给前端。专栏总目录项目总览从普通问答到课程学习 Agent技术栈和工程结构FastAPI、Vue、SQLite、RAG、Agent Harness后端基础设施配置、数据库、模型和 Schema资料上传文件存储、文档记录和重建索引文档解析PDF、Word、PPT、Markdown、代码文件如何进入系统文本切块chunk、metadata、语义类型和 embedding 状态检索系统关键词检索、向量检索、query rewrite 和 rerankLLM 与 Embedding Providerstub、OpenAI-compatible API 和本地模型接入Chat 问答入口兼容普通问答同时接入 Agent 主链路Agent Harness一次 Agent run 的生命周期Planner、Executor 与 Tool RegistryAgent 如何规划和调用工具Agent 校验、安全边界与资料不足处理Agent 记忆短期上下文、长期学习画像和推荐下一步前端工作台资料管理、Agent 任务、Trace、历史和健康状态测试、局限和演进从教学项目走向生产级 Agent SaaS第 7 篇检索系统关键词检索、向量检索、query rewrite 和 rerank7.1 检索入口文件backend/app/services/retrieval.py核心函数defretrieve_chunks(question:str,top_k:int5)-list[RetrievedChunk]:整体流程question - rewrite_retrieval_queries - keyword scoring - vector search - merge ranked chunks - rerank_chunks_with_llm - top_k7.2 RetrievedChunk检索结果使用RetrievedChunk包含chunk_id document_id content source_title source_path source_page language score retrieval_sourceretrieval_source用于区分keyword vector7.3 中文和代码友好的 tokenizetoken 规则TOKEN_REre.compile(r[A-Za-z0-9_]|[\u4e00-\u9fff],re.UNICODE)它能同时处理LoginServlet doPost web.xml Servlet 生命周期 登录流程中文会拆成单字和 bigram英文和代码标识符会转小写。7.4 LLM query rewriterewrite_retrieval_queries会把原始问题改写为更适合检索的查询。例如原问题登录功能为什么跳转失败 可能改写 1. 登录 跳转 失败 2. LoginServlet doPost redirect 3. web.xml servlet mapping 4. session login error如果 LLM 不可用就返回原始问题作为 fallback。7.5 关键词检索关键词检索会对每个 chunk 计算 overlapquery tokens vs content tokens source_path tokens metadata tokens得分len(overlap) / sqrt(content_token_count)这个公式避免长文本天然得分过高。7.6 向量检索文件backend/app/services/vector_store.py向量检索流程问题 - embedding - 遍历已 embedded chunks - cosine_similarity - 按分数排序当前向量存在 SQLite 的 JSON 字段里。按照路线B实现这适合教学和小规模 MVP不适合大规模生产。路线 A专用向量库pgvector / Milvus / ChromaPostgreSQL pgvector专门加了 vector 类型字段数据库原生支持向量相似度计算余弦、欧氏距离SQL 里直接 ORDER BY embedding - ‘[…]’ 做检索数据库底层优化向量索引适合百万级以上向量。向量 元数据统一持久化数据库层内置向量索引与相似度计算。路线 BSQLite 存 JSON 向量SQLite JSON 方案是全量拉取向量到 Python 内存代码里手动算相似度检索逻辑全在 Python 代码全量 / 过滤后取出所有向量loads 转数组numpy 手动算余弦相似度路线 CFAISS 向量检索库内存索引配套外部数据库存业务数据代表faiss搭配 SQLite/PostgreSQL 做元数据存储核心特点只做高速向量计算不负责持久化、不存业务元数据。小规模 demoSQLite / Numpy中等 RAG 应用Chroma大规模高性能向量检索FAISS / Milvus / Qdrant7.7 LLM rerank混合检索后会把候选 chunk 交给 LLM rerankquestion candidates - LLM 返回 chunk_ids 顺序如果 LLM 不可用或返回无效 JSON就使用原始排序。7.8 为什么这个检索设计适合课程 Agent课程资料同时包含自然语言和代码。纯向量检索可能漏掉精确类名纯关键词检索又不理解语义。混合检索能同时照顾课程概念 实验步骤 代码文件 配置文件 报错信息 复习题线索
