5.5 KiB

Raw Permalink Blame History

下一步完成指南

📊 当前状态

已完成基础架构（约30%）：

✅ 完整的项目结构
✅ 数据库层（模型 + 迁移）
✅ 配置和工具模块
✅ ModelManager 服务

🔜 剩余工作

需要创建的文件（按优先级）

1. 服务层（高优先级）

app/services/job_manager.py - 异步任务管理器

# 核心功能：
# - submit_job(job_fn, *args, **kwargs) -> str
# - get_job_status(job_id) -> Dict
# - wait_for_job(job_id, timeout) -> Any

app/services/kb_manager.py - 知识库管理器

# 核心功能：
# - create_kb(name, description) -> KnowledgeBase
# - ingest_documents(kb_id, docs, embedding_name) -> str
# - query_kb(kb_id, query, k) -> List[Document]
# - save_index(kb_id), load_index(kb_id)

app/services/conv_manager.py - 会话管理器

# 核心功能：
# - create_conversation(user_id, title) -> Conversation
# - chat(conv_id, user_input, kb_id, llm_name) -> Message
# - get_messages(conv_id, limit, offset) -> List[Message]

app/services/agent_orchestrator.py - 智能体编排器

# 核心功能：
# - run_agent(agent_name, input, llm_name, tools, kb_id) -> Dict
# - get_logs(run_id) -> List[ToolCall]

app/tools/retriever.py - 检索工具 app/tools/calculator.py - 计算器工具

2. API 层（中优先级）

app/api/v1/models.py - 模型 API

POST /api/v1/models
GET /api/v1/models
GET /api/v1/models/{id}
PUT /api/v1/models/{id}
DELETE /api/v1/models/{id}

app/api/v1/kb.py - 知识库 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

app/api/v1/conv.py - 会话 API

POST /api/v1/conversations
GET /api/v1/conversations/{id}
POST /api/v1/conversations/{id}/messages
GET /api/v1/conversations/{id}/messages

app/api/v1/agent.py - 智能体 API

POST /api/v1/agent/run
GET /api/v1/agent/logs/{run_id}

3. FastAPI 主程序（高优先级）

app/main.py - 应用入口

# 核心内容：
# - FastAPI 应用初始化
# - 路由注册
# - 全局异常处理器
# - CORS 中间件
# - 健康检查端点
# - 启动和关闭事件

4. Docker 配置（中优先级）

docker/Dockerfile docker/docker-compose.yml .dockerignore

5. 测试（低优先级）

tests/conftest.py - pytest 配置 tests/unit/test_model_manager.py tests/unit/test_kb_manager.py tests/integration/test_api_models.py tests/integration/test_api_kb.py

6. 文档（低优先级）

docs/architecture.md - 架构文档 docs/runbook.md - 运维手册 docs/api.md - API 使用指南

🚀 快速完成建议

方式 1: 继续使用 AI 助手

向 AI 助手请求：

请继续创建以下文件：
1. src/app/services/job_manager.py
2. src/app/services/kb_manager.py
... (按上述列表)

方式 2: 参考设计文档手动实现

所有接口定义和实现细节都在：

docs/langchain-learning-kit/DESIGN_langchain-learning-kit.md
docs/langchain-learning-kit/TASK_langchain-learning-kit.md

方式 3: 最小可用版本（MVP）

先实现最核心的功能，跳过测试和文档：

完成服务层（4个文件）
实现 2个 API（Model + KB）
创建 main.py
基础 Docker 配置

预计时间：4-5 小时

📝 当前可以做的事情

1. 安装依赖

cd langchain-learning-kit
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

2. 配置环境变量

cp .env.example .env
# 编辑 .env，填入你的配置：
# - DATABASE_URL
# - OPENAI_API_KEY

3. 初始化数据库

# 方式 1: 使用 Alembic
cd app
alembic upgrade head

# 方式 2: 使用初始化脚本
python scripts/init_db.py

4. 测试已完成的模块

创建测试脚本 test_current.py：

from app.config import get_settings
from app.db.session import init_db_manager
from app.services.model_manager import ModelManager

# 测试配置
settings = get_settings()
print(f"✓ 配置加载成功: {settings.app_name}")

# 测试数据库
db_manager = init_db_manager(settings)
print(f"✓ 数据库连接成功: {settings.database_url}")

# 测试 ModelManager
with db_manager.session_scope() as session:
    manager = ModelManager(session, settings)
    print("✓ ModelManager 初始化成功")

print("\n所有已完成模块测试通过！")

⚠️ 重要提示

MySQL 必须运行: 确保 MySQL 服务启动，数据库已创建
OpenAI API Key: 需要有效的 API Key 才能测试 LLM 功能
Python 版本: 需要 Python 3.11+

🎯 推荐完成顺序

立即创建:
- job_manager.py (最简单，无外部依赖)
- main.py (整合现有代码，可以启动服务)
- models.py API (可以测试 ModelManager)
随后创建:
- kb_manager.py + kb.py API (知识库核心功能)
- conv_manager.py + conv.py API (对话功能)
最后创建:
- agent_orchestrator.py + tools (高级功能)
- Docker 配置
- 测试和文档

📖 参考资料

LangChain 文档: https://python.langchain.com/docs/get_started/introduction
FastAPI 文档: https://fastapi.tiangolo.com/
FAISS 文档: https://github.com/facebookresearch/faiss
SQLAlchemy 文档: https://docs.sqlalchemy.org/

💡 提示

所有的接口定义、数据流、异常处理都已经在设计文档中详细说明。实现时可以直接参考 DESIGN_langchain-learning-kit.md 中的代码示例。

5.5 KiB Raw Permalink Blame History Unescape Escape