224 lines
5.5 KiB
Markdown
224 lines
5.5 KiB
Markdown
|
# 下一步完成指南
|
|||
|
|
|
|||
|
|
## 📊 当前状态
|
|||
|
|
|
|||
|
|
已完成基础架构（约30%）：
|
|||
|
|
- ✅ 完整的项目结构
|
|||
|
|
- ✅ 数据库层（模型 + 迁移）
|
|||
|
|
- ✅ 配置和工具模块
|
|||
|
|
- ✅ ModelManager 服务
|
|||
|
|
|
|||
|
|
## 🔜 剩余工作
|
|||
|
|
|
|||
|
|
### 需要创建的文件（按优先级）
|
|||
|
|
|
|||
|
|
#### 1. 服务层（高优先级）
|
|||
|
|
|
|||
|
|
**`app/services/job_manager.py`** - 异步任务管理器
|
|||
|
|
```python
|
|||
|
|
# 核心功能：
|
|||
|
|
# - 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`** - 知识库管理器
|
|||
|
|
```python
|
|||
|
|
# 核心功能：
|
|||
|
|
# - 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`** - 会话管理器
|
|||
|
|
```python
|
|||
|
|
# 核心功能：
|
|||
|
|
# - 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`** - 智能体编排器
|
|||
|
|
```python
|
|||
|
|
# 核心功能：
|
|||
|
|
# - 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`** - 应用入口
|
|||
|
|
```python
|
|||
|
|
# 核心内容：
|
|||
|
|
# - 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）
|
|||
|
|
|
|||
|
|
先实现最核心的功能，跳过测试和文档：
|
|||
|
|
1. 完成服务层（4个文件）
|
|||
|
|
2. 实现 2个 API（Model + KB）
|
|||
|
|
3. 创建 main.py
|
|||
|
|
4. 基础 Docker 配置
|
|||
|
|
|
|||
|
|
预计时间：4-5 小时
|
|||
|
|
|
|||
|
|
## 📝 当前可以做的事情
|
|||
|
|
|
|||
|
|
### 1. 安装依赖
|
|||
|
|
```bash
|
|||
|
|
cd langchain-learning-kit
|
|||
|
|
python -m venv venv
|
|||
|
|
source venv/bin/activate # Windows: venv\Scripts\activate
|
|||
|
|
pip install -r requirements.txt
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2. 配置环境变量
|
|||
|
|
```bash
|
|||
|
|
cp .env.example .env
|
|||
|
|
# 编辑 .env，填入你的配置：
|
|||
|
|
# - DATABASE_URL
|
|||
|
|
# - OPENAI_API_KEY
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3. 初始化数据库
|
|||
|
|
```bash
|
|||
|
|
# 方式 1: 使用 Alembic
|
|||
|
|
cd app
|
|||
|
|
alembic upgrade head
|
|||
|
|
|
|||
|
|
# 方式 2: 使用初始化脚本
|
|||
|
|
python scripts/init_db.py
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 4. 测试已完成的模块
|
|||
|
|
|
|||
|
|
创建测试脚本 `test_current.py`：
|
|||
|
|
```python
|
|||
|
|
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所有已完成模块测试通过！")
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## ⚠️ 重要提示
|
|||
|
|
|
|||
|
|
1. **MySQL 必须运行**: 确保 MySQL 服务启动，数据库已创建
|
|||
|
|
2. **OpenAI API Key**: 需要有效的 API Key 才能测试 LLM 功能
|
|||
|
|
3. **Python 版本**: 需要 Python 3.11+
|
|||
|
|
|
|||
|
|
## 🎯 推荐完成顺序
|
|||
|
|
|
|||
|
|
1. **立即创建**:
|
|||
|
|
- job_manager.py (最简单，无外部依赖)
|
|||
|
|
- main.py (整合现有代码，可以启动服务)
|
|||
|
|
- models.py API (可以测试 ModelManager)
|
|||
|
|
|
|||
|
|
2. **随后创建**:
|
|||
|
|
- kb_manager.py + kb.py API (知识库核心功能)
|
|||
|
|
- conv_manager.py + conv.py API (对话功能)
|
|||
|
|
|
|||
|
|
3. **最后创建**:
|
|||
|
|
- 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` 中的代码示例。
|