基于Chroma、FastAPI和Llama 3.2的端到端RAG系统

端到端的落地式RAG助手：PDF分块、跨编码器重排序、Chroma、Ollama上的Llama 3.2、FastAPI、Docker，以及用于持续集成的pytest和GitHub Actions。

发布者：REACTAPP.TOP加入本站 2026年9月26日阅读约 8 分钟1747 词

来源: I Built a Production-Style RAG Knowledge Assistant with Python, ChromaDB, FastAPI, and Llama 3.2

面向生产的RAG：从数据导入到CI流程

一个基于事实、可引用来源的知识助手——支持PDF导入、语义搜索、重排序、本地Llama模型生成，采用FastAPI、Docker及GitHub Actions技术，被设计为学习系统而非简单的实验工具。

在完成首次MCP实验后，接下来的需求是实现带有评估与封装功能的检索增强生成，而非再做“在Colab中上传PDF”这样的功能。

目标

将文档索引到持久化向量存储中；通过引用来源检索、重排序并给出答案；通过HTTP提供服务；利用简单评估工具和pytest衡量质量；将系统容器化并与CI流程集成，以便及时发现功能退化问题。

架构

索引流程示意图：

Documents
   ↓
Chunking
   ↓
Embeddings
   ↓
Vector Database
   ↓
Semantic Retrieval
   ↓
Reranking
   ↓
LLM
   ↓
Grounded Answer + Sources

文档加载路径：

PDF Documents
      ↓
Document Loading
      ↓
Text Chunking
      ↓
Embeddings
      ↓
ChromaDB

问答处理流程：

User Question
      ↓
Semantic Retrieval
      ↓
Cross-Encoder Reranking
      ↓
Prompt Construction
      ↓
Llama 3.2
      ↓
Grounded Answer
      ↓
Source Citations

1. 数据导入

将PDF文件加载为类似LangChain风格的文档，保留页面元数据以便日后引用。劣质的加载器会导致后续出现隐性的引用错误。

2. 分块

Chunk size: 1000 characters
Chunk overlap: 200 characters

设置重叠部分可以避免跨分块边界的句子在检索时丢失。应将分块大小视为配置参数，而非埋藏在笔记本单元格中的固定数值。

3. 嵌入模型

sentence-transformers/all-MiniLM-L6-v2

使用小型句子转换器既能让演示在笔记本电脑上运行，也能满足英文技术文档的处理需求。

4. Chroma持久化

Document
   ↓
Chunks
   ↓
Embedding Vectors
   ↓
ChromaDB

分块会被存储为磁盘上的向量，因此重启时无需重新进行完整嵌入。当分块策略发生变化时，需为集合名称添加版本号。

5. 语义检索

documents = vector_store.similarity_search(
    query=query,
    k=top_k
)

在消耗跨编码器计算资源之前，先选取top-k个最近邻作为初步结果。

6. 跨编码器重排序

cross-encoder/ms-marco-MiniLM-L-6-v2

User Question
      ↓
Vector Search
      ↓
Candidate Documents
      ↓
CrossEncoder
      ↓
Reranked Documents

双编码器召回率与交叉编码器精确度是注重质量的任务型检索增强系统的标准两阶段模式。

7. 为大语言模型提供上下文

提示词构建会将排序后的片段作为带编号的来源插入：

[Source 1]
Retrieved document content...

[Source 2]
Retrieved document content...[Source 3]
Retrieved document content...

指示模型仅从这些片段中作答并注明出处；若上下文为空则拒绝响应。

8>通过Ollama使用本地Llama模型

为保障隐私与控制成本，生成操作在本地完成。在配置中固定相关标签，并在接收请求前检查Ollama进程的运行状态。

9. FastAPI接口层

GET /health
POST /query

用于检测服务状态；查询任务型检索增强系统的处理路径。保持服务结构简洁——使用与命令行界面相同的处理流程。

完整查询流程说明：

Question
   ↓
Semantic Retrieval
   ↓
Retrieved Chunks
   ↓
CrossEncoder Reranking
   ↓
Grounded Prompt
   ↓
Llama 3.2
   ↓
Answer + Citations

10. 评估

Questions evaluated: 5
Questions passed: 5
Keyword Match Rate: 100.00%

Hit Rate@K
Recall@K
MRR
Answer Relevance
Faithfulness
Citation Correctness

通过关键词检测及检索指标（命中率、召回率、MRR、答案相关性）可以及时发现嵌入模型或提示词变化时出现的隐性性能下降。

11. pytest

API health endpoint
Document chunking
Document retrieval

3 passed

通过覆盖率检查、分块处理测试以及检索功能的基本测试，能够快速发现问题并使CI流程失败。

12. Docker使用技巧

当模型被嵌入到各个层中时，图像大小往往会出现意外增长：

1.36 GB

1.36 GB

2.56 KB

需正确处理缓存和虚拟环境：

.venv/
__pycache__/
*.pyc
.pytest_cache/
.git/
.github/
.env
chroma_db/
data/sample/*.pdf
*.log

建议在运行时挂载模型缓存，以此保持镜像体积较小。

13. GitHub Actions

Push / Pull Request
        ↓
GitHub Actions
        ↓
Checkout Repository
        ↓
Set Up Python
        ↓
Install Dependencies
        ↓
Run pytest

推送和拉取请求的流程应执行代码格式检查、单元测试，必要时还可运行带有固定装置的简化评估任务。

技术栈、难度等级及后续步骤

Document Processing
        ↓
Chunking
        ↓
Embeddings
        ↓
Vector Storage
        ↓
Retrieval
        ↓
Reranking
        ↓
Prompt Construction
        ↓
LLM Generation
        ↓
Citation Handling
        ↓
Evaluation
        ↓
API
        ↓
Testing
        ↓
Deployment

现存难题并非必须调用大型语言模型，而是数据块边界、重排延迟、引用格式以及Docker层过大的问题。后续升级方向包括混合搜索、更大的带标签评估集、在FastAPI前端添加身份验证功能，以及针对检索延迟的监控机制。

所谓生产级部署，意味着评估与打包流程会与笔记本中的设计思路一同实现——但这并不意味着一台笔记本电脑就能替代整个平台团队。

在配置中记录数据块大小与重叠比例，以确保不同分支中的实验结果具有可比性。

在配置中记录数据块大小和重叠度，以便在不同分支间的实验结果具有可比性。

在配置中记录数据块大小和重叠度，以确保不同分支中的实验结果具有可比性。

在配置中记录数据块大小和重叠度，以便在不同分支间的实验结果具有可比性。

在配置中记录数据块大小和重叠比例，以确保不同分支中的实验结果具有可比性。

← 全部文章发送简报