157 lines
4.7 KiB
Markdown
157 lines
4.7 KiB
Markdown
# ZIP项目功能说明
|
||
|
||
## 概述
|
||
|
||
此功能实现了完全无状态的项目管理，用户必须通过在chat接口的extra参数中提供`zip_url`来动态加载项目数据。系统不再支持传统的project_registry.json配置方式。
|
||
|
||
## 功能特性
|
||
|
||
- **极简无状态项目加载**: 只需提供ZIP URL，系统自动处理所有逻辑
|
||
- **自动缓存**: 相同URL的ZIP文件只会下载一次，提高性能
|
||
- **智能解压**: 自动将ZIP文件解压到项目目录，保持原始结构
|
||
- **自动项目标识**: 基于URL哈希自动生成唯一项目标识
|
||
|
||
## API使用方法
|
||
|
||
### Chat接口
|
||
|
||
直接在请求体中使用最外层参数：
|
||
|
||
```json
|
||
{
|
||
"messages": [
|
||
{
|
||
"role": "user",
|
||
"content": "请分析项目中的数据文件"
|
||
}
|
||
],
|
||
"model": "qwen3-next",
|
||
"model_server": "https://openrouter.ai/api/v1",
|
||
"zip_url": "https://example.com/my-project.zip",
|
||
"stream": false
|
||
}
|
||
```
|
||
|
||
### 参数说明
|
||
|
||
- `model_server`: 模型服务器地址（可选）
|
||
- `zip_url`: ZIP文件的下载链接（必需）
|
||
- `extra`: 其他额外参数（可选）
|
||
|
||
### 系统管理接口
|
||
|
||
#### 清理缓存
|
||
```bash
|
||
POST /system/cleanup-cache
|
||
```
|
||
清理所有下载的ZIP文件缓存。
|
||
|
||
#### 系统状态
|
||
```bash
|
||
GET /system/status
|
||
```
|
||
获取系统状态信息，包括agent池状态。
|
||
|
||
## 工作流程
|
||
|
||
1. **参数验证**: 检查是否提供了必需的zip_url参数
|
||
2. **模型配置**: 如果提供了model_server，将其配置到LLM
|
||
3. **生成项目标识**: 基于URL哈希自动生成唯一项目标识
|
||
4. **下载ZIP**: 系统根据zip_url下载ZIP文件到缓存目录
|
||
5. **缓存检查**: 如果URL已被缓存，直接使用缓存文件
|
||
6. **解压文件**: 将ZIP文件解压到`projects/{url_hash}/`目录，保持原始目录结构
|
||
7. **项目访问**: Agent可以直接访问解压后的所有文件和目录
|
||
|
||
## 缓存机制
|
||
|
||
- ZIP文件基于URL的MD5哈希值进行缓存
|
||
- 缓存位置: `projects/_cache/`
|
||
- 项目目录: `projects/{project_id}_{hash}/`
|
||
- 相同URL不会重复下载，提高性能
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
projects/
|
||
├── _cache/ # ZIP文件缓存
|
||
│ ├── abc123.zip # 基于URL哈希的ZIP文件
|
||
│ └── def456.zip
|
||
├── abc123/ # 解压后的项目目录（URL哈希）
|
||
│ ├── 原始文件和目录结构...
|
||
│ └── 保持ZIP中的完整结构
|
||
└── def456/
|
||
└── 原始文件和目录结构...
|
||
```
|
||
|
||
## 错误处理
|
||
|
||
- 缺少zip_url: 返回400错误
|
||
- 无效URL: 返回400错误
|
||
- 下载失败: 返回400错误
|
||
- 解压失败: 返回400错误
|
||
|
||
## 测试
|
||
|
||
运行测试脚本验证功能：
|
||
|
||
```bash
|
||
python test_zip_feature.py
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **必需参数**: 所有请求都必须提供zip_url参数
|
||
2. **可选参数**: model_server参数可选，用于指定自定义模型服务器
|
||
3. **URL格式**: zip_url必须是有效的HTTP/HTTPS URL
|
||
4. **文件大小**: 建议ZIP文件不超过100MB
|
||
5. **安全性**: 确保ZIP文件来源可信
|
||
6. **网络**: 需要能够访问zip_url指向的资源
|
||
7. **自动标识**: 系统自动基于URL生成项目标识，无需手动指定
|
||
|
||
## 示例使用场景
|
||
|
||
### 1. 临时项目分析
|
||
```python
|
||
import requests
|
||
|
||
response = requests.post("http://localhost:8000/chat/completions", json={
|
||
"messages": [{"role": "user", "content": "分析这个数据集"}],
|
||
"model_server": "https://openrouter.ai/api/v1",
|
||
"zip_url": "https://dataset.example.com/analysis-data.zip"
|
||
})
|
||
```
|
||
|
||
### 2. 多项目对比
|
||
```python
|
||
# 项目1
|
||
response1 = requests.post("http://localhost:8000/chat/completions", json={
|
||
"messages": [{"role": "user", "content": "总结项目1的特点"}],
|
||
"model_server": "https://openrouter.ai/api/v1",
|
||
"zip_url": "https://data.example.com/project1.zip"
|
||
})
|
||
|
||
# 项目2
|
||
response2 = requests.post("http://localhost:8000/chat/completions", json={
|
||
"messages": [{"role": "user", "content": "总结项目2的特点"}],
|
||
"model_server": "https://openrouter.ai/api/v1",
|
||
"zip_url": "https://data.example.com/project2.zip"
|
||
})
|
||
```
|
||
|
||
### 3. 使用默认模型服务器
|
||
```python
|
||
# 不指定model_server，使用默认配置
|
||
response = requests.post("http://localhost:8000/chat/completions", json={
|
||
"messages": [{"role": "user", "content": "分析项目数据"}],
|
||
"zip_url": "https://data.example.com/project.zip"
|
||
})
|
||
```
|
||
|
||
## 技术实现
|
||
|
||
- **下载**: 使用requests库流式下载
|
||
- **解压**: 使用zipfile模块
|
||
- **缓存**: 基于URL哈希的文件缓存
|
||
- **并发安全**: 支持多并发请求处理
|
||
|
||
这个功能实现了极简的无状态项目管理，用户只需在最外层提供model_server和zip_url参数，系统会自动处理模型配置、项目标识生成、下载、解压和缓存，最大程度简化了项目管理的复杂度。 |