首页 / 文章

用两个Python文件实现的文档助手:ChromaDB、LangChain和Claude

将187页的dbt标准PDF文件通过数据导入脚本、本地Hugging Face嵌入模型、ChromaDB以及基于文档的Claude回答功能,转化为可搜索的助手。

发布者:REACTAPP.TOP阅读约 7 分钟1539 词

来源: 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机器人,同时实现自动数据导入功能,以便在文档更新时立即刷新索引。

相关阅读

  • 使用 LangGraph、DeepEval 和 GitLab CI 构建研究智能体团队 — 讲解规划智能体、研究智能体和写作智能体如何在 LangGraph 中共享状态,DeepEval 如何评估内容的准确性,以及 Langfuse 和 GitLab CI 如何确保整个流程的可靠性。
  • 实用笔记:LangChain 系列 1——理解模型、提示词与链结构 — 详细指导如何运用实用笔记:LangChain 系列 1:理解模型、提示词、链结构,包括相关契约、校验机制以及可供团队直接使用的代码模板。
  • LangChain Skills:按需加载智能体专业知识,而非通过单一提示语 —— 别再把所有规则都塞进一个系统提示语中了。了解LangChain Skills如何利用load_skill工具、状态管理及中间件,在需要时才注入相应指令。