中级 22 分钟RAG

使用 ChromaDB 和 Ollama 实现本地 RAG:教程 Python

使用 ChromaDB 和 Ollama 进行本地 RAG:Python 教程

使用 ChromaDB、Ollama 和 Python 在本地实现 RAG,需要三个相互配合的组件:一个将数据持久化到磁盘的向量存储(ChromaDB),一个将文本块转换为向量的嵌入模型(通过 Ollama 运行的 nomic-embed-text),以及一个根据检索到的段落作答的聊天大语言模型。无需 API 密钥,数据不会外泄。本指南将带您在 22 分钟内,从一份原始 PDF 构建出能够引用来源的聊天机器人。

作者: Mohamed Meguedmi·更新于 2026-10-14·已在 Windows、macOS 和 Linux 上测试

#为什么为本地 RAG 选择这套技术栈

许多 RAG 教程都从 LangChain 或 LlamaIndex 开始。这些框架功能强大,但隐藏了底层发生的事情。在这里,我们只使用三个依赖手写整个流水线。您将理解每个步骤,也会知道之后该优化什么。

ChromaDB
开源向量存储,纯 Python,内置持久化模式(SQLite + HNSW 索引)。无需启动服务器。
Ollama
同时为嵌入模型(nomic-embed-text)和聊天 LLM(Qwen 3.5、Granite 4.2、Gemma 4)提供服务。统一的 HTTP 端点位于 localhost:11434。
纯 Python
只需几个函数,无需框架。如果有需要,之后可以接入 LangChain,但起步时并不需要它。
i
您将获得的内容
一个约150行的 Python 脚本,可读取一个文件夹中的 PDF,将其分块并在 ChromaDB 中建立索引,然后用法语回答问题并附上引用来源。全程本地运行,没有任何出站请求。

#先决条件

打造专属 AI 副驾驶的完整套件。

借助我们的经验和引导式路径,打造你的本地副驾驶,上手你的代码助手。

  • 在线空间,终身可用
  • PDF + 文件
  • 30 天内退款
Python 3.10+
ChromaDB 要求最低版本为 3.10。请使用 python --version 检查。
已安装并启动 Ollama
守护进程默认监听 http://localhost:11434。如果您从零开始,请先按照 Ollama 安装指南操作。
8 GB 内存
16 GB 内存较为充裕。9B 聊天模型采用 Q4 量化时占用约 6 GB,嵌入模型占用约 300 MB。
不一定需要 GPU
CPU推理也能正常运行,只是速度较慢。在导入大型语料库时,配备至少6 GB显存的GPU能大幅加快嵌入向量的生成。

#1. 安装 ChromaDB 并准备 Ollama

我们创建一个干净的虚拟环境,安装所需的三个库,并在 Ollama 端下载模型。

Python 环境
python -m venv .venv
source .venv/bin/activate  # sous Windows : .venv\Scripts\activate
pip install chromadb ollama pypdf

三个软件包:chromadb 用于向量存储,ollama 是官方 Python 客户端,pypdf 用于读取 PDF。仅此而已。

Ollama 模型
ollama pull nomic-embed-text:v1.5
ollama pull qwen3.5:9b

该流程使用 nomic-embed-text:v1.5,以明确模型及其任务前缀。它只是一个起始示例;对于法语语料库,请测量搜索结果,并特别比较 BGE-M3。质量还取决于切分方式和文档。

→
检查 Ollama 是否响应
只需执行 curl http://localhost:11434/api/tags,就应该能列出您的模型。如果没有输出,说明守护进程尚未启动:在另一个终端中运行 ollama serve。

#2. 配置嵌入模型

嵌入就是表示文本含义的向量。语义上接近的两段文本,其向量也彼此接近。这是 RAG 的引擎:我们查找嵌入与问题嵌入最相似的文本块。

embed.py — 快速测试
import ollama

resp = ollama.embed(
    model="nomic-embed-text:v1.5",
    input="search_document: Le contrat est résilié en cas de manquement grave.",
)
vec = resp["embeddings"][0]
print(f"Dimension du vecteur : {len(vec)}")
print(f"5 premières valeurs : {vec[:5]}")

您应该会看到输出「Dimension du vecteur : 768」。如果程序报错并显示 model not found,说明尚未执行 ollama pull nomic-embed-text。

i
索引前缀与一致性
Nomic v1.5 要求在每个 chunk 前加上 search_document:,在问题前加上 search_query:。不要在同一个集合中混用由其他模型、维度或约定生成的向量。模型说明页并不能证明您的语料库可以达到“法语 top 5”排名。

#3. 导入法语PDF

摄取过程会做三件事:读取 PDF 的页面,将文本切分成大小合理的块,并在持久化模式下将每个块及其 embedding 存储到 ChromaDB 中。

ingest.py
import os
import chromadb
import ollama
from pypdf import PdfReader

client = chromadb.PersistentClient(path="./chroma_db")
# Nouveau nom : un ancien index "docs" peut encore utiliser la distance L2.
collection = client.get_or_create_collection(
    name="docs_nomic_v15_cosine",
    configuration={"hnsw": {"space": "cosine"}},
)

def chunk_text(text, size=800, overlap=100):
    chunks = []
    start = 0
    while start < len(text):
        end = min(start + size, len(text))
        chunk = text[start:end].strip()
        if chunk:
            chunks.append(chunk)
        start += size - overlap
    return chunks

def ingest_pdf(path):
    reader = PdfReader(path)
    name = os.path.basename(path)
    # Ce dossier d'exemple suppose des noms de fichiers uniques.
    # Retire aussi les chunks devenus obsolètes si le PDF a été raccourci.
    collection.delete(where={"source": name})
    count = 0
    for page_num, page in enumerate(reader.pages):
        text = page.extract_text() or ""
        for i, chunk in enumerate(chunk_text(text)):
            emb = ollama.embed(
                model="nomic-embed-text:v1.5",
                input="search_document: " + chunk,
            )["embeddings"][0]
            collection.upsert(
                ids=[f"{name}-p{page_num}-c{i}"],
                embeddings=[emb],
                documents=[chunk],
                metadatas=[{"source": name, "page": page_num + 1}],
            )
            count += 1
    print(f"OK : {name} ({len(reader.pages)} pages, {count} chunks indexés)")

if __name__ == "__main__":
    for f in os.listdir("./pdfs"):
        if f.lower().endswith(".pdf"):
            ingest_pdf(f"./pdfs/{f}")

分块器将内容切分为每块 800 个字符,相邻块重叠 100 个字符。这是一个起点:块既不会太小(导致上下文不足),也不会太大(导致信号被稀释)。对于内容非常密集的法律文本,可减至 500 个字符;对于排版疏朗的技术手册,可增至 1200 个字符。

→
ChromaDB 的持久化模式
PersistentClient 会将数据库保存在磁盘上。新的名称 docs_nomic_v15_cosine 可避免无提示地沿用旧的 L2 索引。如果更换模型、模型前缀、维度或距离度量,请创建新的集合并重新导入文档。在重新建立索引前备份 PDF:脚本会先移除该文件的旧 chunks。

启动数据导入,导入包含您文档的 ./pdfs/ 文件夹中的内容:

启动数据导入
mkdir -p pdfs
# placez vos PDF dans ./pdfs/
python ingest.py
!
扫描 PDF = 没有文本
pypdf 只能提取 PDF 中原有的文本。如果您的 PDF 是图像扫描件,extract_text() 将返回空内容。这时需要先进行 OCR 处理(使用 Tesseract,或通过 Ollama 使用 Qwen 3.5 9B 这样的多模态视觉模型),然后再导入。

#4. 在 ChromaDB 中进行 top-k 检索

上述集合明确选择了余弦距离,与默认的 L2 设置不同。问题会获得前缀 search_query:,随后 ChromaDB 会在该索引中找出最相近的段落。get_or_create_collection 不会仅仅通过更改变量名就把旧索引转换过来。

search.py
import chromadb
import ollama

client = chromadb.PersistentClient(path="./chroma_db")
collection = client.get_collection(name="docs_nomic_v15_cosine")

def search(question, k=4):
    count = collection.count()
    if count == 0:
        return []
    q_emb = ollama.embed(
        model="nomic-embed-text:v1.5",
        input="search_query: " + question,
    )["embeddings"][0]
    results = collection.query(
        query_embeddings=[q_emb],
        n_results=min(k, count),
    )
    chunks = results["documents"][0]
    metas = results["metadatas"][0]
    return list(zip(chunks, metas))

if __name__ == "__main__":
    hits = search("Quelles sont les conditions de résiliation ?")
    for chunk, meta in hits:
        print(f"[{meta['source']} p.{meta['page']}]")
        print(chunk[:200], "...\n")

k=4 是一个不错的默认值。太小会漏掉相关上下文;太大则会让 LLM 被噪声淹没,并超出上下文窗口的容量。对于非常具体的问题,k=2 就足够了。对于涉及多个方面的问题,将 k 提高到 6。

#5. 带引用的聊天循环

现在把各部分串起来:检索相关文本块,构建包含上下文的提示,通过 Ollama 将其发送给 Qwen 3.5,并要求模型注明信息来源。

chat.py
import ollama
from search import search

SYSTEM = """Tu es un assistant qui répond uniquement à partir du CONTEXTE fourni.
Si la réponse n'est pas dans le contexte, dis-le clairement.
Cite tes sources entre crochets sous la forme [source.pdf p.X]."""

def ask(question):
    hits = search(question, k=4)
    if not hits:
        return "Aucun passage indexé disponible pour répondre."
    context = "\n\n".join(
        f"[{m['source']} p.{m['page']}]\n{c}" for c, m in hits
    )
    prompt = f"CONTEXTE :\n{context}\n\nQUESTION : {question}"
    resp = ollama.chat(
        model="qwen3.5:9b",
        messages=[
            {"role": "system", "content": SYSTEM},
            {"role": "user", "content": prompt},
        ],
        options={"temperature": 0.2, "num_ctx": 8192},
    )
    return resp["message"]["content"]

if __name__ == "__main__":
    while True:
        q = input("\nQuestion (vide pour quitter) > ").strip()
        if not q:
            break
        print("\n" + ask(q))

num_ctx=8192 的上下文必须容纳 chunks、问题、指令和回答;如果内存不足,请减少段落数量。提示词要求提供引用并基于文档作答,但不能保证没有幻觉:请打开引用的页面并核实相关断言。

→
通过流式传输改善 UX
将 ollama.chat 替换为 ollama.chat(..., stream=True),并迭代响应,以便逐步显示 tokens。一旦将这段代码集成到真正的界面中(FastAPI + WebSocket,或 Streamlit),这就至关重要。

#6. 具体示例:针对合同的法律聊天机器人

假设一家事务所想查询 200 份 PDF 格式的服务合同。使用上述技术栈,不到一小时就能搭建一个助手,回答以下这类问题:

典型问题
“哪些合同包含合同终止后期限超过 12 个月的竞业限制条款?”
实际发生的情况
问题的嵌入向量会检索出包含语义相近关键词(竞业限制、终止后、期限)的文本块。Qwen 3.5 阅读这 4 段内容,并在回答中给出相关文件的名称。
隐私保障
任何数据都不会离开这台电脑。不需要 API 密钥。没有任何遥测。这正是本地 RAG 与 OpenAI 封装工具的区别。
!
需了解的局限性
基础 RAG 能很好地回答针对性问题(如「X 条款是什么」),但不擅长回答汇总类问题(如「有多少份合同包含 X」)。对于后者,要么需要一个分多步查询数据库的智能体,要么需要 GraphRAG。这是另一个话题。

#故障排除

ChromaDB 数据导入速度慢
请分别测量 PDF 提取、切分、embedding 和写入所需的时间。使用 ollama ps 检查模型的放置位置。本指南没有确立每秒 50 或 500 个 chunks 的普遍吞吐量。
« model not found »
Ollama 找不到 nomic-embed-text。请重新运行 ollama pull nomic-embed-text,并使用 ollama list 检查。
编造来源的回答
9B 模型仍然偶尔会产生幻觉。如果 VRAM 足够,可以换用 mistral-small(24B,约 14 GB,法语表现非常好)或 qwen3.8:27b。或者在 ChromaDB 之后添加一个重排序器(cross-encoder),过滤误报。
法语(FR)中的 Embeddings 质量较差
请在您已知答案的法语问题上评估检索出的段落。BGE-M3 可直接通过 ollama pull bge-m3 使用。如果更换模型,请在独立集合中重新建立索引;对于所有模型,都不应自动沿用 nomic 前缀。
ChromaDB不断膨胀,没有上限
更新后的脚本会在重新摄取文件前删除该文件的 chunks,并使用稳定 ID 配合 upsert。这也会移除被缩短的 PDF 中的旧页面。它仍是一个简单的本地示例:请保留原始文档和数据库备份。

#2026 年 10 月 14 日的来源与验证

2026 年 10 月 14 日修订:已使用真实 ChromaDB 索引验证余弦排序,并使用测试 PDF 验证重新导入。此次测试的嵌入调用使用本地模拟服务器;Ollama 模型的语义质量和速度仍需在您的语料库上测量。

#深入了解

您已经有了一个可正常运行的 RAG 系统。接下来可以从以下几个方面进一步完善它:

比较法语嵌入模型
我们的《最佳法语嵌入模型》指南比较了 BGE、E5、Solon 和 nomic 在法语内容上的表现。
改进分块
« 分块策略 » 详细介绍语义分块、按 Markdown 标题分块或按段落分块——这些通常最能提升准确性。
添加 reranker
“在自己的流程中添加重排序器”:在 Chroma 之后加入交叉编码器,可将相关性提高 15%。这是顺理成章的下一步。
混合搜索
“BM25 + 向量混合检索”结合了词汇检索与语义检索,一旦涉及大量专业术语或专有名词,就必不可少。
这份指南对您有帮助吗?

有反馈、发现了错误,或想补充说明?请告诉我们,让这份指南对每个人都更有帮助。