Example RAG App — FastAPI + Langfuse

简介

这是一个 RAG 参考实现：FastAPI + Typer CLI、Docker 本地基础设施、LiteLLM（100+ 供应商）与 Langfuse 可观测性，按最佳实践组织代码、类型检查与测试。

• 适合谁： 想要一份干净、可测试、带本地基础设施与可观测性的 RAG 模板的团队
• 可搭配： Python + uv；Docker Compose；FastAPI；Typer；LiteLLM；Langfuse；Qdrant；Redis
• 准备时间： 25–60 分钟

实战建议

• README 标注：用 LiteLLM 代理，通过 OpenAI SDK 适配 100+ 供应商。
• 本地优先：just scaffold 用 docker compose 拉起依赖微服务。
• 开发闭环：Ruff 格式化/检查、Mypy 类型检查，以及 unit/integration/e2e 测试（just test）。

主要内容

把它当作“生产化 RAG 清单”：

1. 本地优先的 IaC。 一条命令拉起向量库/缓存/可观测性，让每个同事能复现问题。
2. 职责拆分。 ingestion/indexing 跟 serving 分开；尽量让 serving API 无状态。
3. 观测检索而不是只看模型。 记录 query、召回文档、chunk 大小，以及每阶段延迟（retrieve → rerank → generate）。
4. 用测试当护栏。 先写 prompt 模板与检索过滤的单测；基础设施稳定后补集成测。

最常见故障是“检索漂移”：索引变了但 prompt/测试没跟上。改 chunking 或过滤策略时，把 ingest 配置固定并重跑评测。

FAQ

必须用 LLM 框架吗？ 答：不必须。README 强调它不依赖框架，直接调用 OpenAI API，并用 LiteLLM 作为供应商代理。

从哪一步开始？ 答：先跑 just scaffold，再 uv run cli；跑通后再替换 ingestion 或按需改造。

怎么控制成本？ 答：先观测 token 与检索 payload 体积，再收紧 chunking、去重上下文，并在关键路径加缓存。