11.2 开发环境搭建 - 人人都会AI编程

在开始动手实现一个 RAG 问答系统之前，先把开发环境准备妥当。本节将带你在本地或云端快速建好一个可运行的实验环境，涵盖 Python 基础环境、必要的依赖库、向量数据库以及大模型 API 的配置。

11.2.1 基础环境要求

操作系统：Windows、macOS 或 Linux 均可，本教程以 macOS / Linux 命令行为例。
Python 版本：3.9 或更高版本（推荐 3.10 或 3.11）。建议使用虚拟环境或 conda 环境隔离项目依赖。
包管理器：pip 或 conda，本教程使用 pip。

快速创建并激活一个干净的虚拟环境：

python -m venv rag_env
source rag_env/bin/activate      # macOS / Linux
# rag_env\Scripts\activate       # Windows

11.2.2 安装核心依赖

RAG 应用通常需要四个方面的库：大模型调用、文档处理、向量化与向量数据库、应用框架。以下是最常用的一组合集：

pip install langchain langchain-openai langchain-community
pip install openai tiktoken
pip install chromadb
pip install pypdf unstructured
pip install python-dotenv

langchain：提供 RAG 链式调用、提示模板、文档加载器等抽象，能显著减少样板代码。
openai / tiktoken：调用 OpenAI 的嵌入和生成模型，也可替换为其他模型供应商。
chromadb：轻量级向量数据库，适合本地开发和 Demo，安装简单无需额外服务。
pypdf / unstructured：用于加载和解析 PDF、Word、网页等多种格式的文档。
python-dotenv：从 .env 文件读取 API Key 等敏感信息，避免硬编码。

提示：如果网络受限或希望完全离线运行，后续可替换为开源的嵌入模型和本地大模型（如 Ollama + nomic-embed-text），本章先以云 API 为例保证通用性和低门槛。

11.2.3 配置 API 密钥

创建项目根目录下的 .env 文件，写入你的 OpenAI API Key（或其他兼容接口）：

OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

在代码中通过 python-dotenv 加载：

from dotenv import load_dotenv
load_dotenv()

这样 langchain 和 openai 包会自动从环境变量中读取密钥。建议将 .env 加入 .gitignore，避免密钥泄露。

11.2.4 启动并验证向量数据库

ChromaDB 作为嵌入式数据库，不需要单独安装服务端。首次使用时，它会自动在当前目录下创建持久化目录或直接运行在内存模式。验证安装：

import chromadb
client = chromadb.Client()
collection = client.create_collection("test")
print("ChromaDB 启动成功，集合创建完成。")

如果没有报错，说明向量数据库已就绪。

11.2.5 创建项目结构

建议采用以下目录结构，方便后续扩展：

my_rag_project/
├── .env                 # 密钥配置
├── requirements.txt     # 依赖列表
├── data/                # 存放待索引的原始文档
│   └── sample.pdf
├── db/                  # ChromaDB 持久化数据（自动生成）
├── app.py               # 主程序入口
└── utils.py             # 工具函数：文档加载、分块等

生成 requirements.txt 以便他人复现：

pip freeze > requirements.txt

11.2.6 连通性测试

编写一个最简单的脚本来验证“嵌入+检索+生成”的链路可通。

# test_env.py
from langchain_openai import OpenAIEmbeddings, ChatOpenAI
from langchain_community.vectorstores import Chroma
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain.schema import Document

# 1. 测试嵌入模型
embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
test_vector = embeddings.embed_query("测试环境是否正常")
print(f"嵌入维度：{len(test_vector)}")  # 应输出 1536 或 512

# 2. 测试向量存储
docs = [Document(page_content="这是测试文档的内容。")]
text_splitter = RecursiveCharacterTextSplitter(chunk_size=100, chunk_overlap=20)
chunks = text_splitter.split_documents(docs)

vectorstore = Chroma.from_documents(
    documents=chunks,
    embedding=embeddings,
    collection_name="test_collection"
)
retriever = vectorstore.as_retriever()
result = retriever.invoke("测试")
print(f"检索到的片段数：{len(result)}")

# 3. 测试生成模型
llm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0)
response = llm.invoke("请用一句话总结RAG的定义。")
print(f"生成结果：{response.content}")

运行 python test_env.py：

如果嵌入维度打印正常，且没有 ModuleNotFoundError，说明依赖安装成功。
如果检索片段数大于 0，说明向量存储和检索正常。
如果生成结果输出了一句话，说明 API 密钥和模型调用正常。

11.2.7 常见问题排查

| 现象 | 可能原因 | 解决方式 |
|------|----------|----------|
| openai.APIConnectionError | 网络不通或需要代理 | 设置 HTTP_PROXY 环境变量；检查防火墙 |
| openai.RateLimitError | 免费额度用尽或超出速率限制 | 绑定信用卡、降低调用频率，或更换 API Key |
| ChromaDB 找不到模块 | 未安装 chromadb 或版本冲突 | 重新安装：pip install chromadb --upgrade |
| PDF 加载乱码 | 文件包含扫描图片，无文字层 | 使用支持 OCR 的加载器（如 pytesseract），或替换为文本格式 PDF |
| 嵌入模型名称不正确 | 使用了已废弃的模型名 | 检查模型清单，使用 text-embedding-3-small 或 text-embedding-3-large |

11.2.8 节约成本的建议

开发调试期间频繁调用 API 会产生费用，尤其在嵌入一大批文档时。以下方式可以帮你控制成本：

使用较小、较便宜的嵌入模型（如 text-embedding-3-small）。
测试阶段只索引少量示例文档（1～5 个文件）。
设置较低的分块大小，减少嵌入总数。
后续章节会介绍如何利用本地开源模型完全替代 API，实现零成本开发。