llm-fastapi-langchain-backend

name	llm-fastapi-langchain-backend
description	指导大模型聊天网页的 FastAPI + LangChain 后端开发。当前后端涉及 uv 环境管理、FastAPI 接口、LangChain 调用链、模型适配、流式响应、SSE 事件、PostgreSQL、pgvector、会话存储、RAG、工具调用、配置、日志、测试或前后端联调时使用此 Skill。每次构建前必须先产出技术文档，并在文档中列出需要用户填写或确认的内容。

大模型 FastAPI + LangChain 后端 Skill

目标

用于建设一个能接收网页用户问题、调用大语言模型、并返回回答的后端服务。后端默认采用 FastAPI + LangChain，Python 环境与依赖默认使用 uv 管理。

开工规则

1. 开始任何后端实现前，先阅读 workflows/project-build-workflow.md。
2. 为本次后端任务新建或更新 docs/technical/ 下的技术文档。
3. 技术文档必须包含“需要用户填写/确认的内容”。
4. 技术文档至少说明目标、API 契约、数据结构、LangChain 调用方式、错误处理、验收标准。
5. 技术文档确认后，再开始写代码。
6. 每次只推进一层能力：环境、接口、模型调用、流式响应、持久化、RAG 逐层建设。

用户填写项要求

如果后端任务涉及配置，必须在技术文档中写清：

• 用户要填哪个文件。
• 用户要填哪些变量。
• 哪些变量必须自己提供。
• 哪些变量可以保持默认。
• 示例值是什么。

典型变量：

DEEPSEEK_API_KEY=用户自己的 DeepSeek API Key
POSTGRES_PASSWORD=用户自己设置的数据库密码
DATABASE_URL=postgresql+psycopg://user:password@localhost:5432/db

uv 环境规则

• 后端依赖由 uv 管理。
• 优先使用 pyproject.toml 记录依赖。
• 不把虚拟环境目录提交进项目。
• .env.example 只放占位变量名，不放真实密钥。

后端分层

• backend/app/api/：FastAPI 路由、请求响应、SSE 输出。
• backend/app/chains/：LangChain 链、提示词组装、RAG 编排。
• backend/app/providers/：模型供应商适配层，避免业务代码绑定单一厂商。
• backend/app/schemas/：Pydantic 请求、响应、事件结构。
• backend/app/services/：发送消息、创建会话、生成回答等业务用例。
• backend/app/repositories/：会话和消息持久化边界。
• backend/app/core/：配置、日志、异常、依赖注入。
• backend/tests/：接口、事件解析、链路单元测试。

记忆系统原则

• 先保存原始会话和消息。
• 再做会话摘要。
• 再做 PostgreSQL + pgvector 语义检索。
• 最后做文档上传、长文切片和 RAG。
• 不把全部历史无脑塞进模型上下文。
• Prompt 组装必须有 token 预算。

API 契约

优先定义这些能力：

• GET /health：健康检查。
• POST /api/chat：发送消息并返回回答，初期可非流式。
• POST /api/chat/stream：发送消息并返回 SSE 流式事件。

SSE 事件建议：

• message_start：助手消息开始。
• token：增量文本。
• message_end：助手消息结束。
• error：可展示错误。

更多后端实现细节见 references/backend-guidelines.md。

验收标准

• uv run 能启动 FastAPI 服务。
• /health 返回正常状态。
• 前端发送一句用户问题后，后端能返回助手回答。
• 缺失 API Key、模型超时、模型异常时有清晰错误。