zhuchaowe/catalog-agent

Fork 0

朱潮 531e6de69e cfg

2025-10-07 22:07:50 +08:00

6.0 KiB

Raw Permalink Blame History

ZIP项目功能说明

概述

此功能实现了完全无状态的项目管理，用户必须通过在chat接口的extra参数中提供zip_url来动态加载项目数据。系统不再支持传统的project_registry.json配置方式。

功能特性

极简无状态项目加载: 只需提供ZIP URL，系统自动处理所有逻辑
自动缓存: 相同URL的ZIP文件只会下载一次，提高性能
智能解压: 自动将ZIP文件解压到项目目录，保持原始结构
自动项目标识: 基于URL哈希自动生成唯一项目标识

API使用方法

Chat接口

直接在请求体中使用最外层参数：

{
  "messages": [
    {
      "role": "user",
      "content": "HP Elite Mini 800 G9ってノートPC？"
    }
  ],
  "stream": true,
  "model": "qwen/qwen3-next-80b-a3b-instruct",
  "api_key": "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",
  "model_server": "https://openrouter.ai/api/v1",
  "zip_url": "http://127.0.0.1:8080/all_hp_product_spec_book2506.zip",
  "extra_prompt": "## 其他说明\n1. 查询的设备类型为第一优先级，比如笔记本和台式机。\n2. 针对\"CPU处理器\"和\"GPU显卡\"的查询，因为命名方式多样性，查询优先级最低。\n3. 如果确实无法找到完全匹配的数据，根据用户要求，可接受性能更高(更低)的CPU处理器和GPU显卡是作为代替。"
  "generate_cfg": {
        # This parameter will affect the tool-call parsing logic. Default is False:
          # Set to True: when content is `<think>this is the thought</think>this is the answer`
          # Set to False: when response consists of reasoning_content and content
        # 'thought_in_content': True,

        # tool-call template: default is nous (recommended for qwen3):
        # 'fncall_prompt_type': 'nous',

        # Maximum input length, messages will be truncated if they exceed this length, please adjust according to model API:
        # 'max_input_tokens': 58000,

        # Parameters that will be passed directly to the model API, such as top_p, enable_thinking, etc., according to the API specifications:
        # 'top_p': 0.8,

        # Using the API's native tool call interface
        # 'use_raw_api': True,
    }
}

参数说明

model_server: 模型服务器地址（可选）
zip_url: ZIP文件的下载链接（必需）
extra: 其他额外参数（可选）

系统管理接口

清理缓存

POST /system/cleanup-cache

清理所有下载的ZIP文件缓存。

系统状态

GET /system/status

获取系统状态信息，包括agent池状态。

工作流程

参数验证: 检查是否提供了必需的zip_url参数
模型配置: 如果提供了model_server，将其配置到LLM
生成项目标识: 基于URL哈希自动生成唯一项目标识
下载ZIP: 系统根据zip_url下载ZIP文件到缓存目录
缓存检查: 如果URL已被缓存，直接使用缓存文件
解压文件: 将ZIP文件解压到projects/{url_hash}/目录，保持原始目录结构
项目访问: 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错误

测试

运行测试脚本验证功能：

python test_zip_feature.py

注意事项

必需参数: 所有请求都必须提供zip_url参数
可选参数: model_server参数可选，用于指定自定义模型服务器
URL格式: zip_url必须是有效的HTTP/HTTPS URL
文件大小: 建议ZIP文件不超过100MB
安全性: 确保ZIP文件来源可信
网络: 需要能够访问zip_url指向的资源
自动标识: 系统自动基于URL生成项目标识，无需手动指定

示例使用场景

1. 临时项目分析

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. 多项目对比

# 项目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. 使用默认模型服务器

# 不指定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参数，系统会自动处理模型配置、项目标识生成、下载、解压和缓存，最大程度简化了项目管理的复杂度。

6.0 KiB Raw Permalink Blame History Unescape Escape