59d4b19d7d
- Phase1/2：移除 MemoirOrchestrator.run 与 process_memoir_segments 别名；文档改为 process_memoir_phase1。 - 槽位校验集中到 stage_constants（filter_stage_slots），批处理与顺序路径及 state_service 写库一致。 - StoryRoute：no_llm/parse_error/invalid_target 保守 new_story；短篇护栏不覆盖这些 fallback。 - Phase2 低置信单路径可选延迟（StoryPipelineResult.deferred）：不写 Chapter/Story，Segment 记录 defer 元数据，冷却内不重复消费；上限后停自动重试，Phase1 同类目新段唤醒池内段。 - Alembic 0017：segments 表 narrative_defer_* 列。 - ProfileAgent：经 LlmGateway/注入 Provider 统一聊天与 JSON，新增测试。 - ImagePromptOrchestrator：LLM 初始化失败可依配置降级或硬失败；补充策略测试。 - 配套单测与 README/本地开发文档表述更新。 Co-authored-by: Cursor <cursoragent@cursor.com>
6.2 KiB
6.2 KiB
Life Echo 本地开发环境配置
本文档介绍如何在本地配置和运行 Life Echo 服务，支持异步 LLM 调用、Redis 会话存储和 Celery 后台任务。
架构概述
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ FastAPI API │────▶│ Redis │◀────│ Celery Worker │
│ (WebSocket) │ │ (会话 + 队列) │ │ (后台任务) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │
│ ┌─────────────────┐ │
└─────────────▶│ PostgreSQL │◀─────────────┘
│ (持久化存储) │
└─────────────────┘
前置要求
- Python 3.10+
- Docker 和 Docker Compose（用于 Redis）
- 有效的 LLM API Key（DeepSeek 或兼容 OpenAI 的服务）
快速开始
1. 启动 Redis
使用 Docker Compose 启动 Redis：
cd api
docker compose -f docker-compose.dev.yml up -d
验证 Redis 是否运行：
docker exec life-echo-redis-dev redis-cli ping
# 应该返回 PONG
2. 配置环境变量
创建或编辑 .env 文件：
cp .env.example .env # 如果有示例文件
配置以下环境变量：
# LLM 配置（DeepSeek）
DEEPSEEK_API_KEY=your_api_key_here
DEEPSEEK_MODEL=deepseek-chat
DEEPSEEK_BASE_URL=https://api.deepseek.com
# 或者使用通用 LLM 配置
# LLM_API_KEY=your_api_key
# LLM_MODEL=gpt-4
# LLM_BASE_URL=https://api.openai.com
# Redis 配置
REDIS_URL=redis://localhost:6379/0
REDIS_SESSION_TTL=86400 # 会话过期时间（秒），默认 24 小时
# 数据库配置（PostgreSQL，与线上一致）
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/life_echo
# JWT 配置
SECRET_KEY=your-secret-key-change-in-production
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=120
3. 安装依赖
cd api
uv sync
4. 数据库迁移（首次或 schema 变更后）
cd api
uv run alembic upgrade head
数据库 schema 由 Alembic 管理，不再在应用启动时自动建表。新库或 schema 变更后需执行上述命令。
5. 启动 FastAPI 服务
cd api
uvicorn main:app --reload --host 0.0.0.0 --port 8000
6. 启动 Celery Worker
在另一个终端窗口：
cd api
celery -A tasks.celery_app worker --loglevel=info --concurrency=2
服务说明
FastAPI API (端口 8000)
- 主 API 服务，处理 HTTP 和 WebSocket 请求
- 对话的实时响应通过异步 LLM 调用生成
- 会话历史存储在 Redis 中
Redis (端口 6379)
- 存储对话会话历史（支持多实例部署）
- 作为 Celery 的消息队列
- 会话数据自动过期（默认 24 小时）
Celery Worker
- 处理回忆录生成等后台任务
- 支持任务重试和失败恢复
- 可以水平扩展
生产环境部署
使用 Docker Compose 一键部署
cd api
# 创建生产环境配置
cp .env .env.prod
# 编辑 .env.prod 配置生产环境变量
# 启动所有服务
docker compose up -d
# 查看日志
docker compose logs -f
# 停止服务
docker compose down
服务扩展
扩展 Celery Worker 以处理更多并发任务：
# 启动额外的 worker
docker compose up -d --scale celery-worker=3
监控（可选）
启用 Flower 监控面板：
- 编辑
docker-compose.yml，取消flower服务的注释 - 重启服务：
docker compose up -d - 访问 http://localhost:5555 查看 Celery 任务监控
常见问题
Redis 连接失败
Redis 连接失败: Error connecting to redis://localhost:6379/0
解决方法：
- 确认 Redis 容器正在运行：
docker ps | grep redis - 检查
REDIS_URL环境变量是否正确 - 如果在 Docker 内运行 API，使用
redis://redis:6379/0
Celery 任务不执行
解决方法：
- 确认 Celery Worker 正在运行
- 检查 Redis 连接是否正常
- 查看 Celery 日志：
celery -A tasks.celery_app worker --loglevel=debug
LLM 调用超时
解决方法：
- 检查网络连接
- 确认 API Key 有效
- 考虑增加超时时间或切换到更快的模型
性能优化建议
支持几百用户
- Redis 集群：对于高并发场景，考虑使用 Redis 集群
- 数据库：使用 PostgreSQL，按负载调整连接池与实例
- Celery Worker：根据负载增加 Worker 数量
- API 实例：使用负载均衡器部署多个 API 实例
配置建议
# Redis 最大内存（防止 OOM）
# 在 docker-compose.yml 中配置：--maxmemory 512mb
# Celery 并发数（根据 CPU 核心数调整）
# 在启动命令中配置：--concurrency=4
# 会话 TTL（根据业务需求调整）
REDIS_SESSION_TTL=86400
API 端点
GET /- API 信息GET /health- 健康检查WS /ws/conversation/{conversation_id}?token=xxx- WebSocket 对话POST /api/auth/register- 用户注册POST /api/auth/login- 用户登录GET /api/conversations/{id}- 获取对话详情GET /api/chapters- 获取章节列表GET /api/books- 获取书籍列表
开发提示
测试 WebSocket 连接
import asyncio
import websockets
import json
async def test():
uri = "ws://localhost:8000/ws/conversation/test-123?token=YOUR_TOKEN"
async with websockets.connect(uri) as ws:
# 发送消息
await ws.send(json.dumps({
"type": "text",
"data": {"text": "你好，我想聊聊我的童年"}
}))
# 接收响应
response = await ws.recv()
print(response)
asyncio.run(test())
手动触发 Celery 任务
from app.tasks.memoir_tasks import process_memoir_phase1
# 同步调用（测试）
result = process_memoir_phase1.delay("user_id", ["segment_id_1", "segment_id_2"])
print(result.get(timeout=60))