用两个Python文件实现的文档助手:ChromaDB、LangChain和Claude
将187页的dbt标准PDF文件通过数据导入脚本、本地Hugging Face嵌入模型、ChromaDB以及基于文档的Claude回答功能,转化为可搜索的助手。
来源: How I Built an AI Agent That Reads Company Docs in 5 Minutes
静态文档存在众所周知的弊端:同事们总是被重复的问题打扰,新成员找不到dbt相关标准,而且所有人都要花费时间在上下文切换上。检索增强生成技术通过让知识库能够按语义而非仅关键词进行搜索,解决了许多这些问题。不过蓝图本身无法回答问题,代码才能。因此这里有一个简单的Python流程,它可以在大约五分钟内读取公司文档,从中构建一个可搜索的“智能体”,为团队提供对话式助手。
整个系统由两个文件组成:
ingest.py是构建工具。运行一次即可处理文档并将其存储在数据库中。ask.py则是对话接口。每当有人有疑问时运行它,它就会根据文档返回答案。
设置
有两样东西是首要的:所需的库以及存储 API 密钥的位置。
需求文件
这些库用于处理文档加载、分块、嵌入向量、向量搜索以及与 Claude 的交互。在项目文件夹中创建 requirements.txt 文件,并列出以下内容:
# Core LangChain — split into standalone packages since 0.2
langchain>=0.2.0
langchain-core>=0.2.0
langchain-community>=0.2.0 # PyPDFLoader still lives here
langchain-text-splitters>=0.2.0 # RecursiveCharacterTextSplitter moved here
langchain-anthropic>=0.1.0
langchain-huggingface>=0.0.3 # HuggingFaceEmbeddings moved here
langchain-chroma>=0.1.0 # Chroma moved here
# Vector store
chromadb>=0.5.0
# PDF loading
pypdf>=4.0.0
# Embeddings
sentence-transformers>=3.0.0
# Claude
anthropic>=0.28.0
# Env vars
python-dotenv>=1.0.0
使用 pip install -r requirements.txt 安装所有依赖项。
.env 文件
Claude 是智能体的语音输出,因此需要 Anthropic API 密钥。切勿在 Python 脚本中直接硬编码密钥,因为意外将其上传到 GitHub 会带来严重的安全风险。应在项目根目录下创建一个隐藏的 .env 文件,并将密钥添加到其中:
ANTHROPIC_API_KEY=your_actual_api_key_here
python-dotenv 库可以让脚本在后台自动读取该文件。
使用 ingest.py 构建知识库
助手在回答问题之前必须先阅读手册。ingest.py 会运行一次,或者在文档有变动时再次运行。它的任务是读取 PDF 文件,将其拆分成易于理解的部分,将这些部分转化为能够体现含义的向量,并将它们保存到数据库中。完整脚本如下:
from langchain_community.document_loaders import PyPDFLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_huggingface import HuggingFaceEmbeddings
from langchain_chroma import Chroma
# Step 1: Load the raw documentation
print("1. Loading the documentation...")
loader = PyPDFLoader("dbt_snowflake_documentation.pdf")
docs = loader.load()
# Step 2: Slice the text into chunks
print("2. Chunking the text...")
text_splitter = RecursiveCharacterTextSplitter(
chunk_size=1000,
chunk_overlap=200
)
chunks = text_splitter.split_documents(docs)
# Step 3: Set up the Embedding Model (The Translator)
print("3. Setting up the embedding model...")
embeddings = HuggingFaceEmbeddings(model_name="all-MiniLM-L6-v2")
# Step 4: Build and save the Vector Database
print("4. Building the ChromaDB brain...")
vector_db = Chroma.from_documents(
documents=chunks,
embedding=embeddings,
persist_directory="./chroma_db"
)
print("Done! The AI Brain is successfully built.")
该脚本的逐步操作流程:
- 加载。
PyPDFLoader读取文档,在此例中为一份共187页的dbt标准PDF文件。 - 分割。 无法将整本书一次性传递给模型,因此文本会被分割成1000字符左右的块,大致对应一个段落。通过200字符的
chunk_overlap设置,可避免跨越两个段落的规则被拆分。 - 嵌入。 所使用的模型是Hugging Face推出的小型开源模型
all-MiniLM-L6-v2,它在本地CPU上运行,无需使用付费的云API,可将每个文本块转换为384维的向量。 - 存储。 这些向量会被保存到ChromaDB中,具体存储路径为
./chroma_db下的相应文件夹。
使用 python ingest.py 运行它。几秒钟后,项目中会出现一个新的 chroma_db 文件夹。该静态文档现已变成一个经过编码且可搜索的存储结构。
通过 ask.py 为其赋予“语音”功能
文档现在以编码形式存储在 ./chroma_db 中。所欠缺的是能够接收问题、查询信息并给出答案的功能。这就是 ask.py,每当有人有疑问时即可运行它:
"""
ask.py — Interactive QA loop. Run this after ingest.py has finished.
Usage:
python ask.py
python ask.py --db ./my_chroma_db --k 6
"""
import os
import argparse
from dotenv import load_dotenv
from langchain_huggingface import HuggingFaceEmbeddings
from langchain_chroma import Chroma
from langchain_anthropic import ChatAnthropic
from langchain_core.prompts import PromptTemplate
from langchain_core.output_parsers import StrOutputParser
from langchain_core.runnables import RunnablePassthrough, RunnableMap
load_dotenv()
# ── CLI args ──────────────────────────────────────────────────────────────────
parser = argparse.ArgumentParser(description="Ask questions against your embedded docs")
parser.add_argument("--db", default="./chroma_db")
parser.add_argument("--k", type=int, default=4)
parser.add_argument("--model", default="claude-sonnet-4-6")
args = parser.parse_args()
# ── Guards ────────────────────────────────────────────────────────────────────
if not os.path.exists(args.db):
print(f"\nERROR: ChromaDB not found at '{args.db}'")
print(" Run ingest.py first.\n")
exit(1)
if not os.getenv("ANTHROPIC_API_KEY"):
print("\nERROR: ANTHROPIC_API_KEY not found in .env file\n")
exit(1)
# ── 1. Embeddings (same model as ingest.py) ───────────────────────────────────
print("\n[1/3] Loading embedding model...")
embeddings = HuggingFaceEmbeddings(
model_name="sentence-transformers/all-MiniLM-L6-v2",
model_kwargs={"device": "cpu"},
encode_kwargs={"normalize_embeddings": True},
)
# ── 2. ChromaDB ───────────────────────────────────────────────────────────────
print(f"[2/3] Connecting to ChromaDB at: {args.db}")
vectorstore = Chroma(
persist_directory=args.db,
embedding_function=embeddings,
collection_name="dbt_docs",
)
doc_count = vectorstore._collection.count()
print(f" {doc_count} chunks loaded")
retriever = vectorstore.as_retriever(
search_type="similarity",
search_kwargs={"k": args.k},
)
# ── 3. Claude ─────────────────────────────────────────────────────────────────
print(f"[3/3] Loading {args.model}...")
llm = ChatAnthropic(
model=args.model,
temperature=0,
max_tokens=2048,
)
# ── Prompt ────────────────────────────────────────────────────────────────────
PROMPT = PromptTemplate.from_template("""You are a helpful assistant for a data engineering team.
Answer the question using ONLY the context provided below.
If the context does not contain enough information, say so clearly — do not make things up.
Be concise and practical. Use code examples when they are present in the context.
Context:
{context}
Question: {question}
Answer:""")
# ── LCEL chain (replaces RetrievalQA) ────────────────────────────────────────
def format_docs(docs):
return "\n\n".join(doc.page_content for doc in docs)
chain = (
RunnableMap({
"context": retriever | format_docs,
"question": RunnablePassthrough(),
})
| PROMPT
| llm
| StrOutputParser()
)
# ── Chat loop ─────────────────────────────────────────────────────────────────
print("\n" + "="*55)
print(" dbt Documentation Agent — ready")
print(f" Model : {args.model}")
print(f" Chunks retrieved per query: {args.k}")
print(" Type 'exit' to quit")
print("="*55 + "\n")
while True:
try:
question = input("Question > ").strip()
except (KeyboardInterrupt, EOFError):
print("\nGoodbye!")
break
if not question:
continue
if question.lower() in ("exit", "quit", "q"):
print("\nGoodbye!")
break
try:
# Retrieve source docs separately so we can display them
source_docs = retriever.invoke(question)
# Run the full chain
answer = chain.invoke(question)
# ── Answer ────────────────────────────────────────────────────────────
print("\n" + "─"*55)
print(answer)
# ── Sources ───────────────────────────────────────────────────────────
print("\n── Sources used " + "─"*39)
seen = set()
for doc in source_docs:
page = doc.metadata.get("page", "?")
source = doc.metadata.get("source", "unknown")
key = (source, page)
if key in seen:
continue
seen.add(key)
preview = doc.page_content.strip()[:280].replace("\n", " ")
print(f"\n [p.{page}] {preview}…")
print("\n" + "─"*55 + "\n")
except Exception as e:
print(f"\nERROR: {e}\n")
尝试使用
通过 python ask.py 启动程序,然后输入诸如“我该如何为阶段模型命名?”之类的问题。该脚本还支持使用 --db 指定不同的 Chroma 文件夹,以及使用 --k 调整每个问题对应的检索块数量,这在答案似乎遗漏了上下文时非常有用。普通的网页答案或编造的答案在这里毫无用处。它的回复大致是“阶段模型应使用 stg_ 前缀”。它并非凭猜测回答,也无需让人去翻阅 PDF 的第14页,而是直接找到了正确的规则,并以资深工程师的方式进行了解释。
现在试着询问一些无关的内容,比如本周巴黎的天气如何。该助手不会凭常识编造答案,而是会查看已获取的文档内容,发现没有相关信息后就会诚实地表示无法根据现有文档给出答案。这种诚实正是让系统在实际应用中值得信赖的重要因素。
对团队而言有哪些变化
这种处理方式不仅适用于dbt,其他任何基于PDF的手册、操作指南或政策文件都可以通过相同的两个脚本处理。由于嵌入模型是在本地运行的,只有最终的问题和检索到的内容片段会发送到外部API。
仅需两个Python文件和几分钟时间,原本几乎无人问津的187页文档便变成了对话型专家。再也不用手动回答“如何为测试模型命名?”的问题,也不用在Confluence中翻找相关链接。该助手会根据你的实际标准立即给出答案。
不过它目前仍运行在笔记本电脑上。接下来的自然步骤是将同一套流程连接到Slack,这样团队成员就可以在他们正在使用的环境中提及@dbt-assistant机器人,同时实现自动数据导入功能,以便在文档更新时立即刷新索引。
相关阅读
- 基于实时EODHD市场数据的LangChain交易智能体构建指南,分步详解 — 为何缺乏真实数据会导致LLM交易智能体失效,ReAct循环的工作原理,以及如何利用EODHD的股价、基本面数据与RSI指标构建三功能LangChain智能体。
- 能在SQLite数据库与网络搜索之间切换的医疗智能体 — 构建能够判断医疗问题是需要查询三个数据集的SQL语句还是进行实时网络搜索的LangChain智能体,以及两次改变设计思路的故障案例。