17 KiB

Raw Blame History

TASK - LangChain Learning Kit 任务拆分

任务依赖图

graph TB
    T1[T1: 项目初始化]
    T2[T2: 数据库层实现]
    T3[T3: 配置和工具模块]
    T4[T4: ModelManager]
    T5[T5: AsyncJobManager]
    T6[T6: KnowledgeBaseManager]
    T7[T7: ConversationManager]
    T8[T8: AgentOrchestrator]
    T9[T9: Model API]
    T10[T10: KB API]
    T11[T11: Conversation API]
    T12[T12: Agent API]
    T13[T13: FastAPI 主程序]
    T14[T14: Docker 配置]
    T15[T15: 测试框架]
    T16[T16: 项目文档]

    T1 --> T2
    T1 --> T3
    T2 --> T4
    T3 --> T4
    T3 --> T5
    T4 --> T6
    T5 --> T6
    T4 --> T7
    T4 --> T8
    T6 --> T8
    T4 --> T9
    T6 --> T10
    T7 --> T11
    T8 --> T12
    T9 --> T13
    T10 --> T13
    T11 --> T13
    T12 --> T13
    T13 --> T14
    T13 --> T15
    T14 --> T16
    T15 --> T16

T1: 项目初始化

输入契约

前置依赖: 无
输入数据: 设计文档 DESIGN_langchain-learning-kit.md
环境依赖: Python 3.11+, Git

输出契约

输出数据:
- 完整的项目目录结构
- requirements.txt 依赖文件
- .env.example 环境变量模板
- .gitignore 文件
- README.md 基础文档
验收标准:
- 目录结构符合设计文档
- requirements.txt 包含所有必要依赖
- .env.example 包含所有配置项
- .gitignore 排除敏感文件和缓存

实现约束

技术栈: Python 3.11
质量要求:
- 依赖版本使用范围约束 (>=x.y,<x+1)
- 环境变量命名遵循 UPPER_SNAKE_CASE

依赖关系

后置任务: T2, T3
并行任务: 无

T2: 数据库层实现

输入契约

前置依赖: T1 (项目结构已创建)
输入数据: 数据库表设计 (DESIGN 文档第4节)
环境依赖: MySQL 8.0+, Python 环境

输出契约

输出数据:
- app/db/models.py: SQLAlchemy 模型定义
- app/db/session.py: 数据库会话管理
- app/db/alembic/: Alembic 迁移配置
- app/db/alembic/versions/001_initial.py: 初始迁移脚本
交付物: 可执行的数据库迁移脚本
验收标准:
- 所有表模型定义完整 (models, knowledge_bases, documents, conversations, messages, tool_calls)
- 外键关系正确
- 索引定义完整
- Alembic 迁移可执行 (alembic upgrade head 成功)
- 数据库连接池配置正确

实现约束

技术栈: SQLAlchemy 2.0+, Alembic 1.12+, PyMySQL
接口规范:
- 使用 declarative_base() 定义模型
- 会话管理使用 sessionmaker + 依赖注入
质量要求:
- 类型提示完整
- 模型包含 __repr__ 方法

依赖关系

前置任务: T1
后置任务: T4, T6, T7, T8
并行任务: T3

T3: 配置和工具模块

输入契约

前置依赖: T1 (项目结构已创建)
输入数据: 配置设计 (DESIGN 文档第7节)
环境依赖: Python 环境

输出契约

输出数据:
- app/config.py: Pydantic Settings 配置类
- app/utils/logger.py: 结构化日志配置
- app/utils/exceptions.py: 自定义异常类
- app/utils/text_splitter.py: 文本分块工具
- app/utils/faiss_helper.py: FAISS 辅助函数
验收标准:
- 配置类支持环境变量读取
- 日志输出为 JSON 格式
- 异常类包含 code, message, status_code
- 文本分块支持按字符数和句子分割
- FAISS 辅助函数支持保存/加载索引

实现约束

技术栈: pydantic-settings, structlog, langchain-text-splitters
接口规范:
- Settings 继承 BaseSettings
- 异常类继承 Exception
质量要求:
- 完整的文档字符串
- 类型提示

依赖关系

前置任务: T1
后置任务: T4, T5, T6
并行任务: T2

T4: ModelManager 实现

输入契约

前置依赖: T2 (数据库模型), T3 (配置和异常)
输入数据: ModelManager 设计 (DESIGN 文档 3.1 节)
环境依赖: OpenAI API Key (可选，用于测试)

输出契约

输出数据:
- app/services/model_manager.py: ModelManager 类实现
验收标准:
- 实现 CRUD 方法 (create_model, get_model, list_models, update_model, delete_model)
- 实现 get_llm() 方法返回 LangChain LLM 实例
- 实现 get_embedding() 方法返回 Embeddings 实例
- 支持默认模型逻辑
- 配置中的 ${VAR} 变量替换功能
- 异常处理完善

实现约束

技术栈: langchain-openai, SQLAlchemy
接口规范:

class ModelManager:
    def __init__(self, db_session: Session, settings: Settings)
    def create_model(name: str, type: str, config: Dict) -> Model
    def get_llm(name: Optional[str] = None) -> BaseLLM
    def get_embedding(name: Optional[str] = None) -> Embeddings

质量要求:
- 单元测试覆盖核心方法
- 配置验证

依赖关系

前置任务: T2, T3
后置任务: T6, T7, T8, T9
并行任务: T5

T5: AsyncJobManager 实现

输入契约

前置依赖: T3 (日志和异常)
输入数据: AsyncJobManager 设计 (DESIGN 文档 3.5 节)
环境依赖: Python asyncio

输出契约

输出数据:
- app/services/job_manager.py: AsyncJobManager 类实现
验收标准:
- 支持异步任务提交 (submit_job)
- 任务状态查询 (get_job_status)
- 任务结果等待 (wait_for_job)
- 异常捕获和记录
- 任务 ID 生成 (UUID)

实现约束

技术栈: Python asyncio, UUID
接口规范:

class AsyncJobManager:
    async def submit_job(job_fn: Callable, *args, **kwargs) -> str
    async def get_job_status(job_id: str) -> Dict
    async def wait_for_job(job_id: str, timeout: int) -> Any

质量要求:
- 线程安全
- 超时处理

依赖关系

前置任务: T3
后置任务: T6
并行任务: T4

T6: KnowledgeBaseManager 实现

输入契约

前置依赖: T2 (数据库模型), T3 (工具模块), T4 (ModelManager), T5 (JobManager)
输入数据: KBManager 设计 (DESIGN 文档 3.2 节)
环境依赖: FAISS, OpenAI Embeddings

输出契约

输出数据:
- app/services/kb_manager.py: KnowledgeBaseManager 类实现
验收标准:
- 知识库 CRUD (create_kb, get_kb, list_kb, delete_kb)
- 文档摄取 (ingest_documents) - 支持异步
- 向量检索 (query_kb)
- FAISS 索引持久化 (save_index, load_index)
- 文档分块处理
- 批量嵌入计算
- 索引状态查询

实现约束

技术栈: FAISS, langchain-community, langchain-openai
接口规范:

class KnowledgeBaseManager:
    def __init__(self, db_session, model_manager, job_manager, settings)
    def create_kb(name: str, description: str) -> KnowledgeBase
    async def ingest_documents(kb_id: int, docs: List[Dict], embedding_name: str) -> str
    def query_kb(kb_id: int, query: str, k: int, embedding_name: str) -> List[Document]
    def save_index(kb_id: int) -> bool
    def load_index(kb_id: int) -> FAISS

质量要求:
- FAISS 索引路径管理清晰
- 错误处理完善
- 单元测试和集成测试

依赖关系

前置任务: T2, T3, T4, T5
后置任务: T8, T10
并行任务: T7

T7: ConversationManager 实现

输入契约

前置依赖: T2 (数据库模型), T4 (ModelManager)
输入数据: ConvManager 设计 (DESIGN 文档 3.3 节)
环境依赖: LangChain Memory

输出契约

输出数据:
- app/services/conv_manager.py: ConversationManager 类实现
验收标准:
- 会话 CRUD (create_conversation, get_conversation)
- 消息管理 (add_message, get_messages)
- 聊天功能 (chat) - 支持 RAG
- 会话历史构建
- Prompt 模板管理

实现约束

技术栈: LangChain, langchain-openai
接口规范:

class ConversationManager:
    def __init__(self, db_session, model_manager, kb_manager, settings)
    def create_conversation(user_id: int, title: str) -> Conversation
    async def chat(conv_id: int, user_input: str, kb_id: int, llm_name: str, use_rag: bool) -> Message
    def get_messages(conv_id: int, limit: int, offset: int) -> List[Message]

质量要求:
- RAG 上下文注入正确
- 消息历史管理

依赖关系

前置任务: T2, T4
后置任务: T11
并行任务: T6

T8: AgentOrchestrator 实现

输入契约

前置依赖: T2 (数据库模型), T4 (ModelManager), T6 (KBManager)
输入数据: Agent 设计 (DESIGN 文档 3.4 节)
环境依赖: LangChain Agents

输出契约

输出数据:
- app/services/agent_orchestrator.py: AgentOrchestrator 类实现
- app/tools/retriever.py: Retriever Tool
- app/tools/calculator.py: Calculator Tool
验收标准:
- Agent 执行 (run_agent)
- 工具调用日志 (log_tool_call, get_logs)
- Retriever Tool 实现
- Calculator Tool 实现
- Agent 工具注册机制

实现约束

技术栈: LangChain Agents, langchain-openai
接口规范:

class AgentOrchestrator:
    def __init__(self, db_session, model_manager, kb_manager, settings)
    async def run_agent(agent_name: str, input: str, llm_name: str, tools: List[str], kb_id: int) -> Dict
    def get_logs(run_id: str) -> List[ToolCall]

class RetrieverTool:
    name = "knowledge_base_search"
    def run(query: str, kb_id: int) -> str

class CalculatorTool:
    name = "calculator"
    def run(expression: str) -> str

质量要求:
- 工具调用审计完整
- 异常处理

依赖关系

前置任务: T2, T4, T6
后置任务: T12
并行任务: T7

T9: Model API 实现

输入契约

前置依赖: T4 (ModelManager)
输入数据: API 设计 (DESIGN 文档 5.2 节)
环境依赖: FastAPI

输出契约

输出数据:
- app/api/v1/models.py: Model API 路由
验收标准:
- POST /api/v1/models (创建模型)
- GET /api/v1/models (列出模型)
- GET /api/v1/models/{id} (获取模型)
- PUT /api/v1/models/{id} (更新模型)
- DELETE /api/v1/models/{id} (删除模型)
- Pydantic 请求/响应模型
- 统一响应格式

实现约束

技术栈: FastAPI, Pydantic
接口规范: RESTful API
质量要求:
- 参数验证
- 错误处理
- OpenAPI 文档

依赖关系

前置任务: T4
后置任务: T13
并行任务: T10, T11, T12

T10: Knowledge Base API 实现

输入契约

前置依赖: T6 (KBManager)
输入数据: API 设计 (DESIGN 文档 5.2 节)
环境依赖: FastAPI

输出契约

输出数据:
- app/api/v1/kb.py: KB API 路由
验收标准:
- POST /api/v1/kb (创建知识库)
- GET /api/v1/kb (列出知识库)
- POST /api/v1/kb/{kb_id}/ingest (文档摄取)
- POST /api/v1/kb/{kb_id}/query (向量检索)
- GET /api/v1/kb/{kb_id}/status (索引状态)
- 文件上传支持 (txt)
- 异步任务响应

实现约束

技术栈: FastAPI, UploadFile
接口规范: RESTful API
质量要求:
- 文件大小限制
- 异步处理
- 进度查询

依赖关系

前置任务: T6
后置任务: T13
并行任务: T9, T11, T12

T11: Conversation API 实现

输入契约

前置依赖: T7 (ConvManager)
输入数据: API 设计 (DESIGN 文档 5.2 节)
环境依赖: FastAPI

输出契约

输出数据:
- app/api/v1/conv.py: Conversation API 路由
验收标准:
- POST /api/v1/conversations (创建会话)
- GET /api/v1/conversations/{id} (获取会话)
- POST /api/v1/conversations/{id}/messages (发送消息)
- GET /api/v1/conversations/{id}/messages (消息历史)
- 分页支持

实现约束

技术栈: FastAPI, Pydantic
接口规范: RESTful API
质量要求:
- 流式响应 (可选)
- 分页查询

依赖关系

前置任务: T7
后置任务: T13
并行任务: T9, T10, T12

T12: Agent API 实现

输入契约

前置依赖: T8 (AgentOrchestrator)
输入数据: API 设计 (DESIGN 文档 5.2 节)
环境依赖: FastAPI

输出契约

输出数据:
- app/api/v1/agent.py: Agent API 路由
验收标准:
- POST /api/v1/agent/run (执行 Agent)
- GET /api/v1/agent/logs/{run_id} (获取日志)
- 工具选择参数

实现约束

技术栈: FastAPI, Pydantic
接口规范: RESTful API
质量要求:
- 执行日志详细
- 超时处理

依赖关系

前置任务: T8
后置任务: T13
并行任务: T9, T10, T11

T13: FastAPI 主程序实现

输入契约

前置依赖: T9, T10, T11, T12 (所有 API 路由)
输入数据: 架构设计
环境依赖: FastAPI

输出契约

输出数据:
- app/main.py: FastAPI 应用入口
- app/api/v1/__init__.py: 路由聚合
验收标准:
- FastAPI 应用初始化
- 所有路由注册
- 全局异常处理器
- CORS 中间件
- 健康检查端点
- OpenAPI 文档配置
- 应用可启动 (uvicorn)

实现约束

技术栈: FastAPI, uvicorn
接口规范:
- API 前缀 /api/v1
- 自动生成 OpenAPI 文档
质量要求:
- 依赖注入配置
- 中间件配置

依赖关系

前置任务: T9, T10, T11, T12
后置任务: T14, T15
并行任务: 无

T14: Docker 配置实现

输入契约

前置依赖: T13 (应用可运行)
输入数据: 部署设计 (DESIGN 文档第10节)
环境依赖: Docker

输出契约

输出数据:
- docker/Dockerfile: 应用镜像定义
- docker/docker-compose.yml: 服务编排
- .dockerignore: 构建排除文件
验收标准:
- Dockerfile 多阶段构建
- docker-compose 包含 MySQL 和 App 服务
- 数据卷挂载正确
- 环境变量传递
- 健康检查配置
- 容器可成功启动

实现约束

技术栈: Docker, Docker Compose
质量要求:
- 镜像体积优化
- 安全最佳实践

依赖关系

前置任务: T13
后置任务: T16
并行任务: T15

T15: 测试框架实现

输入契约

前置依赖: T13 (应用完整)
输入数据: 测试策略 (DESIGN 文档第9节)
环境依赖: pytest

输出契约

输出数据:
- tests/conftest.py: pytest 配置和 fixture
- tests/unit/test_model_manager.py: ModelManager 单元测试
- tests/unit/test_kb_manager.py: KBManager 单元测试
- tests/integration/test_api_models.py: Model API 集成测试
- tests/integration/test_api_kb.py: KB API 集成测试
- pytest.ini: pytest 配置文件
验收标准:
- 测试数据库 fixture
- 核心服务单元测试
- API 集成测试
- 测试覆盖率 > 60%
- 所有测试通过

实现约束

技术栈: pytest, httpx, pytest-asyncio
质量要求:
- 测试隔离
- Mock 外部依赖

依赖关系

前置任务: T13
后置任务: T16
并行任务: T14

T16: 项目文档实现

输入契约

前置依赖: T14, T15 (完整系统)
输入数据: 所有实现代码
环境依赖: Markdown

输出契约

输出数据:
- README.md: 项目介绍和快速开始
- docs/architecture.md: 架构文档
- docs/runbook.md: 运维手册
- docs/api.md: API 使用指南
验收标准:
- README 包含完整的安装和运行步骤
- 架构文档包含系统设计图
- Runbook 包含常见问题和解决方案
- API 文档包含所有端点的示例

实现约束

技术栈: Markdown
质量要求:
- 文档清晰易懂
- 代码示例可运行

依赖关系

前置任务: T14, T15
后置任务: 无
并行任务: 无

任务执行顺序总结

第一批 (可并行):

T1: 项目初始化

第二批 (可并行):

T2: 数据库层
T3: 配置和工具

第三批 (可并行):

T4: ModelManager
T5: AsyncJobManager

第四批 (可并行):

T6: KnowledgeBaseManager
T7: ConversationManager

第五批:

T8: AgentOrchestrator

第六批 (可并行):

T9: Model API
T10: KB API
T11: Conversation API
T12: Agent API

第七批:

T13: FastAPI 主程序

第八批 (可并行):

T14: Docker 配置
T15: 测试框架

第九批:

T16: 项目文档

总体复杂度评估

任务	复杂度	预估时间	风险等级
T1	低	30分钟	低
T2	中	1小时	低
T3	中	1小时	低
T4	中	1.5小时	中
T5	低	45分钟	低
T6	高	2小时	中
T7	中	1.5小时	中
T8	高	2小时	中
T9	低	45分钟	低
T10	中	1小时	低
T11	低	45分钟	低
T12	低	45分钟	低
T13	低	30分钟	低
T14	中	1小时	低
T15	中	1.5小时	中
T16	低	1小时	低

总计: 约 17 小时

17 KiB Raw Blame History

TASK - LangChain Learning Kit 任务拆分

任务依赖图

T1: 项目初始化

输入契约

输出契约

实现约束

依赖关系

T2: 数据库层实现

输入契约

输出契约

实现约束

依赖关系

T3: 配置和工具模块

输入契约

输出契约

实现约束

依赖关系

T4: ModelManager 实现

输入契约

输出契约

实现约束

依赖关系

T5: AsyncJobManager 实现

输入契约

输出契约

实现约束

依赖关系

T6: KnowledgeBaseManager 实现

输入契约

输出契约

实现约束

依赖关系

T7: ConversationManager 实现

输入契约

输出契约

实现约束

依赖关系

T8: AgentOrchestrator 实现

输入契约

输出契约

实现约束

依赖关系

T9: Model API 实现

输入契约

输出契约

实现约束

依赖关系

T10: Knowledge Base API 实现

输入契约

输出契约

实现约束

依赖关系

T11: Conversation API 实现

输入契约

输出契约

实现约束

依赖关系

T12: Agent API 实现

输入契约

输出契约

实现约束

依赖关系

T13: FastAPI 主程序实现

输入契约

输出契约

实现约束

依赖关系

T14: Docker 配置实现

输入契约

输出契约

实现约束

依赖关系

T15: 测试框架实现

输入契约

输出契约

实现约束

依赖关系

T16: 项目文档实现

输入契约

17 KiB

Raw Blame History