从零搭一套能检查的 RAG 基础设施

如果一套 AI 应用只有一个接口和一个模型，看起来很快，后面通常很难改。数据放在哪里，搜索怎么做，任务怎么定时，服务挂了怎么发现，这些问题迟早要补回来。

这个项目把它们拆成了几层。第一周不做问答，先把底座跑通。你最后应该能看到一个健康检查接口，并能在浏览器里打开 FastAPI 文档。

先看清楚这一套系统

• FastAPI：接收请求，提供接口和自动文档。
• PostgreSQL：保存论文标题、摘要、正文和元数据。
• OpenSearch：负责后面的全文搜索、向量搜索和混合搜索。
• Airflow：把每天抓取论文这类任务变成可调度的流程。
• Ollama：先作为本地模型服务放在底座里，后面再接入 RAG 。
• Docker Compose：把这些服务放进同一个网络，并管理数据卷。

七篇教程会沿着这条线往上加：第一篇搭底座；第二篇把论文接进来；第三篇先把关键词搜索做好；第四篇再加切块、向量和混合排序；第五篇接本地模型做问答；第六篇补缓存和监控；第七篇让系统根据问题决定是否检索，并接到手机聊天入口。

这张路线只在这里说一次。后面的文章直接进入当周的动手部分。

准备环境

仓库 README 当前给出的基础条件是：Python 3.12 及以上、 Docker Desktop 、 UV 、至少 8GB 内存和 20GB 可用磁盘。 Linux 、 macOS 、 Windows 都可以，但 Docker 的内存分配要留意。

git clone https://github.com/jamwithai/production-agentic-rag-course.git
cd production-agentic-rag-course
cp .env.example .env
uv sync

.env 先不要急着改很多。仓库的默认配置用于本地启动，后面到需要外部 embedding 、监控或机器人时，再补对应变量。不要把密钥直接写进 Markdown 、代码或提交记录。

第一次启动

docker compose up --build -d
docker compose ps
curl http://localhost:8000/api/v1/health

如果健康检查路径在你检出的版本里不同，打开 http://localhost:8000/docs，搜索 health，以交互文档列出的路径为准。 README 同时列出了这些本地入口：

• FastAPI 文档：http://localhost:8000/docs
• Airflow：http://localhost:8080
• OpenSearch：http://localhost:9200
• OpenSearch Dashboards：http://localhost:5601
• Ollama：http://localhost:11434

先逐个打开，不要只看 docker compose ps 里的容器状态。容器显示 Up，不等于应用已经能接受请求。

验证顺序

第一步看容器：

docker compose ps
docker compose logs --tail=80 api

第二步看 FastAPI：浏览器访问 /docs，确认页面能打开。

第三步看 OpenSearch：

curl http://localhost:9200

第四步看 Airflow：打开 8080，确认页面能加载。账号密码要从项目生成的认证文件或当前环境配置中读取，不要照抄别人的默认密码。

第五步再测 Ollama 。第一周并不要求必须下载模型，服务健康就够了。如果机器内存允许，可以只拉一个小模型：

make ollama-pull MODEL=llama3.2:1b
make ollama-test MODEL=llama3.2:1b

模型下载会占用磁盘和内存。只是验证接口时，不要为了“完整”直接拉 8B 模型。

Docker Compose 到底解决了什么

Compose 文件把服务放进同一个网络。容器之间用服务名通信，宿主机才用 localhost 加端口访问。这个区别很容易弄错：API 容器访问数据库时，通常写数据库服务名；你在电脑上执行 curl，才写 localhost:8000。

数据卷也很重要。数据库和 OpenSearch 的数据如果没有卷，容器删掉以后，练习结果也会消失。第一次学习可以用：

docker compose down

要彻底清空数据才使用：

docker compose down --volumes

第二条命令会删除卷，等于把本地数据一起清掉。遇到端口冲突时，先查 8000 、 8080 、 5432 、 9200 是否已经被其他程序占用，不要直接清库。

常见问题的排查顺序

• 容器反复重启：看对应服务日志，不要先重装 Docker 。
• OpenSearch 启动很慢：给 Docker 更多内存，等待一两分钟后再查日志。
• API 能打开但数据库报错：检查 .env 中的连接地址，以及容器内外地址是否混用。
• 端口被占用：停止冲突服务，或改宿主机映射端口；不要随意改容器内部端口。
• Windows 上命令不通：先确认是在 PowerShell 、 WSL 还是 Git Bash 中执行，三者的路径写法不完全一样。

这一周的完成标准

你不需要在第一周做出一个“会聊天”的页面。完成标准是：服务能启动，健康检查能返回，API 文档能打开，数据库和搜索服务能访问，停止后能按预期恢复。做到这里，后面每一周加功能时才有地方落脚。

项目地址： https://github.com/jamwithai/production-agentic-rag-course