MemeMeow/api.md

VVQuest API 文档

目录

1. 接口概览
2. 接口详情
3. API 配置文件说明

接口概览

接口路径	方法	描述
/search	POST	执行图片搜索
/generate-cache	POST	触发缓存生成（后台任务）
/config	GET	获取当前配置
/api-config	PUT	更新API配置
/download-model	POST	下载指定模型
/models	GET	获取可用模型列表
/mode/{mode}	PUT	切换运行模式
/model/{model_id}	PUT	切换本地模型

接口详情

1. 搜索图片

• 路径: /search

• 方法: POST

• 描述: 执行图片搜索

• 请求体 (application/json):

  {
    "query": "搜索关键词",
    "n_results": 5  // 可选，默认值 5
  }
  

• 成功响应

  • 状态码: 200
  • 内容: JSON 格式数据（具体字段需参考实现）

• 错误响应

  • 状态码: 422 (请求体验证失败)

2. 生成缓存

• 路径: /generate-cache
• 方法: POST
• 描述: 触发后台缓存生成任务
• 成功响应
  • 状态码: 200
  • 内容: JSON 格式空对象

3. 获取配置

• 路径: /config
• 方法: GET
• 描述: 获取当前API配置
• 成功响应
  • 状态码: 200
  • 内容: JSON 格式配置信息

4. 更新配置

• 路径: /api-config

• 方法: PUT

• 描述: 更新API配置

• 请求体 (application/json):

  {
    "api_key": "新的API密钥",  // 可选（可为 null）
    "base_url": "新的基础URL"  // 可选（可为 null）
  }
  

• 成功响应

  • 状态码: 200
  • 内容: JSON 格式空对象

• 错误响应

  • 状态码: 422 (请求体验证失败)

5. 下载模型

• 路径: /download-model

• 方法: POST

• 描述: 下载指定模型

• 请求体 (application/json):

  {
    "model_id": "模型ID"
  }
  

• 成功响应

  • 状态码: 200
  • 内容: JSON 格式空对象

• 错误响应

  • 状态码: 422 (请求体验证失败)

6. 模型列表

• 路径: /models
• 方法: GET
• 描述: 获取可用模型列表
• 成功响应
  • 状态码: 200
  • 内容: JSON 格式模型列表

7. 切换模式

• 路径: /mode/{mode}

• 方法: PUT

• 描述: 切换系统运行模式

• 路径参数

  • mode (字符串): 目标模式名称

• 成功响应

  • 状态码: 200
  • 内容: JSON 格式空对象

• 错误响应

  • 状态码: 422 (参数验证失败)

8. 切换模型

• 路径: /model/{model_id}

• 方法: PUT

• 描述: 切换本地使用的模型

• 路径参数

  • model_id (字符串): 目标模型ID

• 成功响应

  • 状态码: 200
  • 内容: JSON 格式空对象

• 错误响应

  • 状态码: 422 (参数验证失败)

API 配置文件说明

API 配置文件为 /config/api_config.yaml ，用于配置 API 的行为。

全局配置

api:
  generate_cache: False      # 是否自动生成缓存（默认关闭）

• 作用
  • 当 generate_cache: True 时，系统启动后自动执行缓存生成任务。

端点权限控制

protected_mode: False      # 是否启用保护模式（默认关闭）
allowed_endpoints:
  - "/search"                # 允许访问的API端点（仅保护模式开启时生效）

• 作用
  • 当 protected_mode: True 时，仅列出的端点可被外部访问。
  • 默认允许 /search，其他接口需手动添加（如 /config）。

请求限流配置

rate_limit:
  enabled: True              # 是否启用请求限流
  requests: 10               # 每分钟最大请求数
  window: 60                 # 时间窗口（单位：秒）
  storage: "memory"          # 限流计数存储方式（支持 memory/redis）

• 参数说明

  字段	类型	可选值	说明
  enabled	bool	True/False	是否启用限流
  requests	int	正整数	单位时间窗口内允许的最大请求数
  window	int	正整数（秒）	限流时间窗口长度
  storage	string	memory/redis	计数器存储方式

• 示例场景

  • requests: 10 + window: 60 表示每60秒最多处理 10 次请求。
  • 若使用 redis 存储，需确保 Redis 服务已配置并连接。

运行模式配置

mode: "local"                # 系统运行模式（api/local）
api_mode_config:
  default_api_key: "your-key-here"     # API 默认密钥
  default_base_url: "https://api.example.com"  # API 默认服务地址
model: "bge-m3"            # 当前使用的模型ID（需与模型列表匹配）

• 模式说明

  模式值	描述
  local	本地模式，优先使用本地模型和资源
  api	API 模式，依赖外部服务（需配置 api_mode_config 中的密钥和基础URL）

• API 模式专用配置

  • default_api_key: 调用外部 API 所需的身份凭证（建议通过环境变量注入）。
  • default_base_url: 外部 API 服务的基础地址（例如 OpenAI 兼容接口）。

• 本地模式专用配置

  • model: 当前使用的模型ID（需与 models 配置中的模型ID一致）。

修改配置后，请重启服务以生效。