RAG（检索增强生成）技术能让 AI 基于指定文档回答问题，避免 "一本正经地胡说八道"。本文将手把手教你搭建一个可本地运行的 RAG 聊天助手，涵盖环境配置、模型选型、核心逻辑实现到前端交互的完整流程，即使是新手也能轻松上手。

一、开发环境搭建：打好基础是关键

在开始写代码前，我们需要先配置好开发环境，解决依赖冲突，并管理好敏感信息。

1.1 核心依赖安装：三大工具缺一不可

RAG 应用的运行需要三个核心工具：

• Chainlit：轻量级 Python 前端框架，用于快速搭建聊天界面
• llama-index：RAG 引擎，负责文档处理、向量检索和 LLM 调用的整合
• python-dotenv：管理环境变量，避免敏感信息硬编码

打开终端，执行以下命令安装：

pip install chainlit llama-index python-dotenv

安装完成后，我们可以通过 Chainlit 的测试命令验证环境是否正常：

chainlit hello

如果运行时报错（常见于 pydantic 版本冲突），会出现类似ImportError: cannot import name 'BaseModel' from 'pydantic'的错误。这是因为 Chainlit 对 pydantic（数据验证库）的版本兼容性要求较严格，解决方案如下：

# 卸载当前pydantic版本
pip uninstall pydantic -y

# 安装兼容的2.9.2版本
pip install pydantic==2.9.2

重新执行chainlit hello，如果能看到一个带示例对话的网页界面，说明前端环境配置成功。

1.2 环境变量配置：敏感信息要藏好

API 密钥、认证密码等敏感信息绝对不能直接写在代码里（否则上传代码仓库时可能泄露）。我们用.env文件统一管理这些信息。

在项目根目录创建.env文件，内容如下：

# .env文件
# Chainlit的访问认证密钥（可自定义复杂字符串）
CHAINLIT_AUTH_SECRET=my_chainlit_secret_123

# 月之暗面Kimi模型API密钥（需从官网申请）
KIMI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxx

# DeepSeek模型API密钥（可选，用于切换模型测试）
DEEPSEEK_API_KEY=sk-yyyyyyyyyyyyyyyyyyyy

• CHAINLIT_AUTH_SECRET：用于 Chainlit 应用的登录认证，防止未授权用户访问
• 模型 API 密钥：需要从对应平台（如月之暗面、DeepSeek）注册账号后获取，是调用大语言模型的 "通行证"

后续代码会通过python-dotenv加载这些变量，避免硬编码风险。

二、模型配置：RAG 的 "大脑" 与 "眼睛"

RAG 的核心是 "先检索再生成"，这需要两个关键模型：嵌入模型（将文本转为向量，负责 "检索"）和大语言模型（LLM）（负责 "生成" 回答）。

2.1 嵌入模型：让计算机 "看懂" 文本的向量魔法

嵌入模型的作用是将文本（文档或问题）转为高维向量 —— 向量之间的相似度越高，说明文本语义越接近。这是实现 "根据问题找相关文档" 的核心。

我们选择中文支持优秀且轻量的BAAI/bge-small-zh-v1.5模型（适合本地 CPU 运行），创建embeddings.py文件：

# embeddings.py
from llama_index.embeddings.huggingface import HuggingFaceEmbedding

def get_embed_model():
    """加载本地中文嵌入模型"""
    # 模型会自动下载到~/.cache/huggingface/hub（首次运行需要等待下载）
    embed_model = HuggingFaceEmbedding(
        model_name="BAAI/bge-small-zh-v1.5",  # 中文优化的轻量模型
        model_kwargs={"device": "cpu"},  # 本地无GPU时用cpu，有GPU可改为"cuda"
        embed_batch_size=10  # 批量处理文本的数量（根据内存调整）
    )
    return embed_model

# 全局实例化，避免每次调用重复加载模型（节省内存）
embed_model = get_embed_model()

为什么选这个模型？

• 中文效果好：专门针对中文语料优化，比英文模型（如 OpenAI 的 text-embedding）更适合中文文档
• 轻量高效：模型体积小（约 300MB），本地 CPU 即可运行，无需高端显卡
• 开源免费：可商用，无需 API 调用费用

2.2 LLM 配置：让 AI 基于文档 "说人话"

大语言模型（LLM）负责根据检索到的文档和问题生成自然语言回答。我们以月之暗面的 Kimi 模型为例（兼容 OpenAI 接口），创建llms.py文件：

# llms.py
from llama_index.llms.openai import OpenAI  # 通用接口类，适配兼容OpenAI格式的模型
from dotenv import load_dotenv  # 加载.env文件
import os

# 加载.env中的环境变量
load_dotenv()

def get_llm(model_name: str = "kimi"):
    """获取配置好的LLM实例，支持多模型切换"""
    if model_name == "kimi":
        return OpenAI(
            model="kimi-k2-0711-preview",  # Kimi模型名称（需与官网一致）
            api_key=os.getenv("KIMI_API_KEY"),  # 从环境变量取密钥
            api_base="https://api.moonshot.cn/v1"  # Kimi的API地址
        )
    elif model_name == "deepseek":
        return OpenAI(
            model="deepseek-chat",  # DeepSeek模型名称
            api_key=os.getenv("DEEPSEEK_API_KEY"),
            api_base="https://api.deepseek.com/v1"  # DeepSeek的API地址
        )
    else:
        raise ValueError(f"不支持的模型：{model_name}")

# 默认使用Kimi模型（可随时切换为deepseek）
llm = get_llm("kimi")

关键细节：

• 接口兼容性：很多第三方模型（如 Kimi、DeepSeek）都实现了与 OpenAI 一致的 API 格式（/v1/chat/completions），因此可以直接用 llama-index 的OpenAI类调用，无需重复开发接口逻辑
• 模型切换：通过model_name参数可快速切换模型，方便测试不同模型的回答效果
• API 密钥安全：通过os.getenv从环境变量读取密钥，避免代码泄露

三、RAG 核心逻辑：从文档到回答的完整链路

RAG 的核心流程是 "文档→索引→检索→生成"。我们需要实现两个关键功能：将文档转为可检索的索引，以及结合索引和 LLM 的聊天引擎。

3.1 文档索引：给文档建一个 "向量图书馆"

索引是文档的 "向量化存储库"—— 它会将文档拆分成小片段，用嵌入模型转为向量，然后保存起来。后续提问时，就能通过向量相似度快速找到相关片段。

创建base_rag.py文件，实现索引的创建与加载：

# base_rag.py
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.core.storage.storage_context import StorageContext
from llama_index.core.persistence import PersistentDirectoryStore
from embeddings import embed_model  # 导入前面配置的嵌入模型
import os

# 索引文件保存目录（会自动创建）
INDEX_DIR = "./index"

def create_index(documents=None):
    """
    创建或加载文档索引
    - 若documents不为空：基于新文档创建/更新索引
    - 若documents为空：加载已保存的索引
    """
    # 1. 处理输入的文档（用户上传的文件路径列表）
    if documents:
        # 读取用户上传的文档（支持txt、pdf、md等格式）
        reader = SimpleDirectoryReader(documents=documents)
        docs = reader.load_data()  # 解析文档内容
    else:
        docs = None  # 无新文档时，不读取

    # 2. 配置索引的存储路径
    storage_context = StorageContext.from_defaults(
        persist_dir=INDEX_DIR,
        docstore=PersistentDirectoryStore.from_persist_dir(persist_dir=INDEX_DIR)
    )

    # 3. 生成或加载索引
    if not os.path.exists(INDEX_DIR) or documents:
        # 情况1：索引目录不存在，或有新文档→创建新索引
        index = VectorStoreIndex.from_documents(
            docs,  # 文档内容
            storage_context=storage_context,  # 存储配置
            embed_model=embed_model  # 用我们的嵌入模型生成向量
        )
        # 保存索引到本地（下次可直接加载，无需重新处理文档）
        index.storage_context.persist(persist_dir=INDEX_DIR)
    else:
        # 情况2：索引已存在且无新文档→直接加载
        index = VectorStoreIndex.from_storage(storage_context=storage_context)
    
    return index

索引工作原理：

1. 文档拆分：SimpleDirectoryReader会将长文档拆分成短片段（默认约 500 字），避免向量模型对长文本处理效果差的问题
2. 向量生成：VectorStoreIndex.from_documents调用嵌入模型，将每个片段转为向量
3. 持久化存储：向量和文档元数据被保存到./index目录，下次启动时直接加载，无需重复处理文档（节省时间和资源）
4. 增量更新：当用户上传新文件时（documents不为空），会自动基于新文件更新索引，不影响旧文档

3.2 聊天引擎：检索与生成的 "执行者"

聊天引擎是 RAG 的 "指挥官"—— 它接收用户问题后，先从索引中找到相关文档片段，再结合对话历史，让 LLM 生成基于文档的回答。

在base_rag.py中继续添加聊天引擎的实现：

# base_rag.py（续）
from llama_index.core.memory import ChatMemoryBuffer  # 对话记忆
from llama_index.core.chat_engine import ContextChatEngine  # RAG专用聊天引擎
from llms import llm  # 导入前面配置的LLM

def create_chat_engine(index):
    """基于索引创建带对话记忆的聊天引擎"""
    # 1. 配置对话记忆（保存最近1024 token的聊天记录）
    # 作用：让AI理解上下文，比如用户问"上文提到的XX是什么"时能正确回答
    memory = ChatMemoryBuffer.from_defaults(token_limit=1024)
    
    # 2. 创建RAG聊天引擎
    chat_engine = ContextChatEngine.from_defaults(
        index=index,  # 用于检索相关文档
        memory=memory,  # 用于保存对话历史
        llm=llm,  # 用于生成回答的大模型
        # 系统提示词：约束AI行为（必须基于文档回答，不编造信息）
        system_prompt="你是一个基于文档的问答助手。回答必须严格结合提供的文档内容，"
                      "如果文档中没有相关信息，直接说明'文档中未提及该内容'，不要编造。"
    )
    
    return chat_engine

聊天引擎的工作流程：

1. 接收用户问题（如 "文档中提到的核心功能有哪些？"）
2. 用嵌入模型将问题转为向量，从索引中检索最相似的文档片段（默认返回前 5 个）
3. 整合 "问题 + 检索到的文档片段 + 对话历史"，生成给 LLM 的提示
4. 调用 LLM 生成回答，并返回给用户

其中，system_prompt非常重要 —— 它能约束 LLM 的回答范围，避免 AI 脱离文档 "自由发挥"。

四、前端交互：用 Chainlit 搭建可视化界面

有了核心逻辑后，我们需要一个用户能操作的界面（上传文件、输入问题、查看回答）。Chainlit 可以快速实现这个功能，且支持实时流式输出（类似 ChatGPT 的打字机效果）。

4.1 应用初始化与认证控制

创建app_ui.py文件，先实现应用启动逻辑和登录认证：

# app_ui.py
import chainlit as cl  # Chainlit前端框架
from dotenv import load_dotenv
from base_rag import create_index, create_chat_engine  # 导入RAG核心逻辑
import os

# 加载.env环境变量
load_dotenv()

# 1. 登录认证：防止未授权访问（生产环境可对接数据库或OAuth）
@cl.authorize_callback
def auth_callback(username: str, password: str):
    # 简单示例：仅允许用户名admin、密码admin登录
    # 实际使用时可改为查询数据库验证用户
    return username == "admin" and password == "admin"

# 2. 聊天开始时的初始化操作
@cl.on_chat_start
async def on_chat_start():
    # 向用户发送欢迎消息
    await cl.Message(content="欢迎使用RAG聊天助手！请上传文档（支持txt、pdf等）或直接提问～").send()
    
    # 加载已有的索引（如果存在）
    index = create_index()
    # 创建聊天引擎，并保存到当前用户的会话中（多用户隔离）
    chat_engine = create_chat_engine(index)
    cl.user_session.set("chat_engine", chat_engine)

关键说明：

• 认证机制：@cl.authorize_callback是 Chainlit 提供的登录验证钩子，这里用简单的用户名密码示例，实际部署时可替换为更安全的方式（如数据库存储密码哈希）
• 用户会话：cl.user_session用于存储当前用户的聊天引擎实例，确保多用户同时使用时，各自的文档和对话历史互不干扰（A 用户的文档不会被 B 用户检索到）

4.2 处理用户操作：文件上传与提问

继续在app_ui.py中实现用户交互逻辑（上传文件和处理提问）：

# app_ui.py（续）
@cl.on_message
async def on_message(message: cl.Message):
    # 从当前用户会话中获取聊天引擎
    chat_engine = cl.user_session.get("chat_engine")
    
    # 1. 处理用户上传的文件（如果有）
    if message.elements:  # message.elements包含用户上传的所有文件
        documents = []  # 存储文件路径
        for element in message.elements:
            # 只处理文件类型（可扩展支持图片OCR等）
            if element.type in ["file", "image"]:
                # 创建临时目录保存文件
                temp_dir = "./temp"
                os.makedirs(temp_dir, exist_ok=True)  # 确保目录存在
                file_path = f"{temp_dir}/{element.name}"
                
                # 保存文件内容到本地
                with open(file_path, "wb") as f:
                    f.write(element.content)  # element.content是文件二进制数据
                
                documents.append(file_path)  # 记录文件路径
        
        if documents:
            # 通知用户正在处理文件
            await cl.Message(content="正在处理上传的文档，请稍等...").send()
            # 基于新文件更新索引
            index = create_index(documents=documents)
            # 用新索引重建聊天引擎，并更新会话
            chat_engine = create_chat_engine(index)
            cl.user_session.set("chat_engine", chat_engine)
            # 通知用户处理完成
            await cl.Message(content="文档处理完成！现在可以提问啦～").send()
            return  # 处理完文件后，等待用户输入问题
    
    # 2. 处理用户的提问（流式返回回答）
    # 初始化一个空消息，用于实时更新回答内容
    msg = cl.Message(content="")
    await msg.send()  # 先发送空消息，后续逐步更新
    
    # 调用聊天引擎处理问题，流式获取回答（逐token返回）
    response = chat_engine.stream_chat(message.content)
    for token in response.response_gen:  # 遍历生成的每个token
        msg.content += token  # 拼接token
        await msg.update()  # 实时更新消息（打字机效果）

流程解析：

• 文件上传：

  1. 用户上传文件后，Chainlit 将文件内容封装在message.elements中
  2. 代码将文件保存到./temp目录，避免内存占用过高
  3. 调用create_index更新索引，确保新文件能被检索到
  4. 重建聊天引擎，让后续提问使用最新索引

• 提问处理：

  1. 调用chat_engine.stream_chat获取流式回答（LLM 生成一个字就返回一个字）
  2. 通过msg.update()实时更新前端显示，实现 "边生成边显示" 的效果，提升用户体验

五、完整运行流程：从启动到交互

现在，我们已经完成了所有核心代码，接下来看看如何运行整个应用：

1. 准备工作：

   • 确保.env文件中已填写正确的 API 密钥（如 KIMI_API_KEY）
   • 项目目录结构应为：

     项目根目录/
     ├── .env
     ├── embeddings.py
     ├── llms.py
     ├── base_rag.py
     └── app_ui.py
     

2. 启动应用：在终端执行命令：

   chainlit run app_ui.py -w
   

   （-w参数表示热重载，修改代码后无需重启应用）

3. 使用流程：

   • 打开终端中显示的本地地址（通常是http://localhost:8000）
   • 输入用户名admin、密码admin登录
   • 上传文档（如 txt、pdf），等待处理完成
   • 输入问题（如 "文档中提到的核心功能是什么？"），查看 AI 基于文档的回答

六、扩展与优化方向

这个基础版本已经能实现核心功能，你还可以从以下方向优化：

1. 支持更多文件类型：默认支持 txt、pdf、md，可通过 llama-index 的UnstructuredReader扩展为支持 docx、ppt 等
2. 优化检索精度：调整文档拆分长度（默认 500 字）、增加检索数量（默认 5 条）
3. 增强安全性：替换简单认证为数据库验证，加密存储 API 密钥
4. 添加历史记录：用数据库保存用户对话，支持查看历史
5. 本地 LLM 部署：如果有 GPU，可替换为本地运行的 LLM（如 Qwen、Llama3），摆脱 API 依赖

通过本文，你已经掌握了 RAG 聊天助手的完整搭建流程 —— 从环境配置到模型选型，从核心逻辑到前端交互。这个框架不仅能用于文档问答，还能扩展为知识库管理、客服助手等场景。动手试试吧，让 AI 真正成为你的 "文档解读专家"！