# LQAgentWritePlatform — 项目结构文档 > 施工方案 AI 自动生成平台 — FastAPI + Celery + LangGraph + Milvus --- ## 目录树 ``` LQAgentWritePlatform/ │ ├── README.md # 项目说明与部署指南 ├── requirements.txt # Python 依赖清单 ├── run.sh # Uvicorn 启动脚本（默认 8003 端口） ├── deploy_agent.sh # 一键部署脚本（git pull → build → deploy） ├── Dockerfile # 应用镜像（基于 base 镜像，仅复制源码） ├── Dockerfile.base # 基础镜像（Python 3.12-slim + 所有 pip 依赖） ├── .dockerignore # 构建排除文件 │ ├── config/ # 配置与资源 │ ├── config.ini # 运行时配置（数据库连接、密钥、端点） │ ├── config.ini.template # 配置模板（可提交到版本库） │ ├── model_setting.yaml # 模型路由配置（功能→模型映射） │ ├── prompt/ # AI Prompt 模板 │ │ ├── intent_prompt.yaml # 意图分类 Prompt │ │ └── system_prompt.yaml # 系统 Prompt │ ├── sql/ # 数据库初始化脚本 │ │ ├── doc_callback_task_id_table.sql # 文档回调任务表 │ │ ├── lq_db.sql # 数据库初始化 │ │ └── test.sql # 测试数据 │ └── yolo/ # YOLO 模型权重 │ └── best.pt │ ├── core/ # 业务逻辑层 │ ├── base/ # 通用基础设施 │ │ ├── progress_manager.py # 任务进度追踪（Redis-backed） │ │ ├── sse_manager.py # SSE（Server-Sent Events）统一管理器 │ │ └── workflow_manager.py # 工作流提交与任务管理 │ └── construction_write/ # 施工方案编写业务 │ ├── component/ │ │ ├── milvus.py # Milvus 轻量条件查询工具 │ │ ├── outline_generator.py # 大纲生成核心逻辑 │ │ ├── similar_fragment_service.py # 相似片段检索服务 │ │ └── state_models.py # LangGraph 状态模型定义 │ └── workflows/ │ ├── agent.py # Agent 工作流入口（测试/预留） │ └── outline_workflow.py # LangGraph 大纲生成工作流 │ ├── docker/ # Docker 编排 │ └── docker-compose.yml # Redis + App 服务编排 │ ├── foundation/ # 基础设施层（可复用） │ ├── ai/ # AI 模型层 │ │ └── models/ │ │ ├── model_config_loader.py # 从 YAML 加载模型配置 │ │ ├── model_handler.py # 模型调用统一处理器 │ │ └── rerank_model.py # Reranker 模型封装（预留未接入） │ ├── database/ # 数据库层 │ │ └── base/ │ │ └── vector/ # 向量存储 │ │ ├── base_vector.py # 抽象接口定义 │ │ ├── milvus_vector.py # Milvus 实现（dense+sparse 混合搜索） │ │ └── pg_vector.py # PostgreSQL pgvector 实现 │ ├── infrastructure/ # 基础设施 │ │ ├── cache/ # 缓存与锁 │ │ │ ├── redis_config.py # Redis 配置 │ │ │ ├── redis_connection.py # Redis 连接池 │ │ │ ├── async_redis_lock.py # 异步分布式锁 │ │ │ └── redis_lock.py # 同步分布式锁 │ │ ├── config/ │ │ │ └── config.py # INI 配置读取单例（config_handler） │ │ ├── messaging/ # 消息队列 │ │ │ ├── celery_app.py # Celery 应用定义 │ │ │ └── tasks.py # Celery 任务定义 │ │ └── tracing/ # 链路追踪 │ │ ├── trace_context.py # Trace ID 上下文 │ │ └── celery_trace.py # Celery Trace 传播 │ ├── observability/ # 可观测性 │ │ ├── logger/ │ │ │ └── loggering.py # 结构化日志配置（文件轮转） │ │ └── monitoring/ │ │ └── time_statistics.py # 耗时统计工具 │ └── utils/ # 工具函数 │ ├── common.py # 通用工具 │ ├── md5.py # MD5 哈希 │ ├── redis_utils.py # Redis 辅助函数 │ ├── tool_utils.py # 杂项工具 │ └── yaml_utils.py # YAML 解析辅助 │ ├── logs/ # 运行日志（自动生成） │ ├── agent_debug.log │ ├── agent_info.log │ ├── agent_warning.log │ └── construction_write/ │ ├── celery_worker.err.log │ ├── celery_worker.out.log │ ├── construction_write_debug.log │ ├── construction_write_info.log │ └── construction_write_warning.log │ ├── server/ # 服务入口 │ └── app.py # FastAPI 应用创建、路由注册、CORS、Celery 生命周期 │ └── views/ # HTTP API 路由层 ├── construction_write/ │ ├── outline_views.py # 大纲生成、重生成、任务管理、上下文生成 │ ├── content_completion.py # 内容补全 API（续写/扩写/润色/补全） │ └── similar_plan_recommend.py # 相似片段检索 API ``` --- ## API 接口总览 所有业务接口均挂载在 `/sgbx` 前缀下。 ### 通用接口 | 方法 | 路径 | 说明 | |------|------|------| | GET | `/health` | 服务健康检查 | | GET | `/celery/status` | Celery Worker 状态 | ### 大纲管理（`outline_views.py`） | 方法 | 路径 | 说明 | 响应 | |------|------|------|------| | POST | `/sgbx/generating_outline` | SSE 流式生成大纲 | SSE | | POST | `/sgbx/regenerate_outline` | SSE 流式重新生成指定章节 | SSE | | POST | `/sgbx/task_cancel` | 取消运行中的任务 | JSON | | GET | `/sgbx/task_status` | 查询任务状态 | JSON | | GET | `/sgbx/active_tasks` | 列出所有活跃任务 | JSON | ### 上下文/内容生成（`outline_views.py` + `content_completion.py`） | 方法 | 路径 | 说明 | 响应 | |------|------|------|------| | POST | `/sgbx/context_generate` | SSE 流式生成段落内容 | SSE | | GET | `/sgbx/context_generate_health` | 上下文生成健康检查 | JSON | | GET | `/sgbx/context_generate_modes` | 列出可用模式（续写/扩写/润色/补全） | JSON | | POST | `/sgbx/content_completion` | SSE 流式内容补全（独立端点） | SSE | | GET | `/sgbx/content_completion_health` | 内容补全健康检查 | JSON | | GET | `/sgbx/content_completion_modes` | 列出补全模式 | JSON | ### 相似片段检索（`similar_plan_recommend.py`） | 方法 | 路径 | 说明 | 响应 | |------|------|------|------| | POST | `/sgbx/similar_fragment_search` | Milvus 混合检索相似片段 | JSON | | GET | `/sgbx/similar_fragment_search_health` | 检索服务健康检查 | JSON | --- ## 核心模块说明 ### 1. `server/app.py` — 应用入口 - 创建 FastAPI 实例，配置 CORS 中间件 - 注册所有路由模块（outline / content_completion / similar_fragment） - 通过 lifespan 钩子管理 Celery Worker 的自动启停 - 提供 `/health` 和 `/celery/status` 工具接口 ### 2. `core/base/` — 通用基础能力 | 模块 | 职责 | |------|------| | `progress_manager.py` | Redis-backed 进度管理，Redis 不可用时降级为内存存储 | | `sse_manager.py` | SSE 连接管理，按任务 ID 路由事件到对应客户端 | | `workflow_manager.py` | Celery 任务提交、进度查询、结果获取的统一编排层 | ### 3. `core/construction_write/` — 施工方案业务 | 模块 | 职责 | |------|------| | `component/outline_generator.py` | 大纲生成核心：模板加载、并发章节生成、进度追踪 | | `component/similar_fragment_service.py` | 相似片段检索：两阶段 pipeline（混合召回 → parent_id 聚合） | | `component/milvus.py` | Milvus 轻量条件查询（`condition_query`），按 `parent_id` 回查全文 | | `workflows/outline_workflow.py` | LangGraph 状态机：初始化 → 加载模板 → 生成大纲 → 推荐案例 → 关联知识库 → 完成 | ### 4. `foundation/` — 基础设施层 | 子模块 | 职责 | |--------|------| | `ai/models/` | LLM 调用：支持多模型路由（DashScope/蜀天/豆包/本地），Embedding、Reranker 封装 | | `database/base/vector/` | 向量存储：Milvus（dense+sparse 混合）+ PostgreSQL pgvector 两套实现 | | `infrastructure/cache/` | Redis 连接池 + 分布式锁（同步/异步） | | `infrastructure/config/` | INI 配置读取单例，支持 `${ENV_VAR}` 变量展开 | | `infrastructure/messaging/` | Celery 异步任务框架，支持 Windows `--pool=solo` | | `infrastructure/tracing/` | 请求级 Trace ID，自动传播至 Celery 任务 | | `observability/` | 结构化日志（文件轮转 10MB/5 备份）+ 耗时统计 | | `utils/` | MD5、Redis 辅助、YAML 解析、通用工具 | ### 5. `config/` — 配置管理 | 文件 | 说明 | |------|------| | `config.ini` | 运行时配置：数据库连接、Redis、Milvus、API 密钥、日志级别 | | `config.ini.template` | 配置模板，不含敏感信息，可提交到版本库 | | `model_setting.yaml` | 功能到模型的路由映射（文档分类/完整性审查/RAG/语法检查等各有专用模型） | | `prompt/*.yaml` | AI Prompt 模板（意图分类 + 系统提示词） | --- ## 技术栈 | 类别 | 技术 | |------|------| | Web 框架 | FastAPI + Uvicorn | | 异步任务 | Celery（Redis broker） | | 工作流 | LangGraph | | 向量数据库 | Milvus（dense embedding + BM25 sparse 混合搜索） | | 缓存/消息 | Redis | | LLM | 通义千问 Qwen3.5 系列 / 蜀天算力 / 豆包 / DeepSeek | | Embedding | Qwen3-Embedding-8B | | Reranker | BGE-reranker-v2-m3 / Qwen3-Reranker-8B（预留未接入） | | 部署 | Docker Compose（base 镜像 + 应用镜像两阶段构建） | --- ## 部署架构 ``` 外部请求 │ ▼ 端口 18003 ──► Docker 容器 (8003) ──► FastAPI + Uvicorn │ │ ├── outline_generation (Celery async) ─┤ ├── content_completion (SSE stream) │ └── similar_fragment_search (Milvus) ──┤ │ Redis ◄──────── 任务状态 / 缓存 / 分布式锁 Milvus ◄─────── 向量检索（dense+sparse 混合） ``` **镜像构建流程：** 1. `Dockerfile.base` → `lq-agent-base:latest`（预装所有 pip 依赖，仅在 requirements.txt 变化时重建） 2. `Dockerfile` → `lq_agent_write_platform_server_dev:vX.XX`（基于 base 镜像复制源码，秒级构建） **一键部署：** 执行 `deploy_agent.sh` → git pull → 停容器 → 构建镜像 → 更新 compose 版本号 → 启动