v1.8.0

v1.8.0

此版本主要聚焦于代码结构的深度重构、核心功能的完善与增强，以及多项关键错误修复。项目核心逻辑已进一步模块化并迁移至 app/core/ 目录下的细分功能模块，显著提升了代码的可维护性和可扩展性。用户侧的 Gemini 原生缓存管理功能已全面实装，后台缓存自动清理任务也已修复并正常运行。

主要更新内容：

核心功能增强与完善

• API 密钥管理 (app/core/keys)

  • 双模式存储: 引入 KEY_STORAGE_MODE 环境变量，支持 API 密钥在 'database' (SQLite 持久化) 和 'memory' (环境变量加载) 两种模式间灵活切换。
  • 数据库支持: 为 'database' 模式新增了 ApiKey SQLAlchemy 模型，并实现了完整的 CRUD 操作 (app/core/database/models.py, app/core/database/utils.py)。
  • 统一管理器: APIKeyManager (app/core/keys/manager.py) 经过重构，现能够统一处理两种存储模式下的密钥加载、智能选择及状态管理，同时支持在内存模式下对密钥进行临时操作。
  • Web UI 与 API 适配: 密钥管理 Web UI (/manage/keys) 及相关的管理 API (/api/manage/keys/*) 已全面适配两种存储模式，方便管理员进行操作。

• Gemini API 原生缓存 (app/core/cache, app/api/cache_endpoints.py)

  • 功能开关: 新增 ENABLE_NATIVE_CACHING 环境变量，用于全局控制是否启用 Gemini API 的原生缓存功能。
  • 用户侧管理接口:
    • 提供 API 端点 (GET /v1/caches, DELETE /v1/caches/{cache_id})，允许用户通过 API 列出和删除自己的缓存条目。
    • 提供 Web UI 页面 (/manage/caches)，方便用户在浏览器中进行可视化缓存管理。
  • 后台自动清理机制: 缓存的后台自动清理定时任务 (app/core/cache/cleanup.py) 已成功修复并激活。该任务现在能正确使用 AsyncSession 定期清理数据库中过期和无效的缓存记录。
  • 数据模型增强: CachedContent 数据库模型 (app/core/database/models.py) 已包含 user_id 和 key_id 字段，实现了缓存条目与用户及 API 密钥的精确关联。
  • 智能选择集成: APIKeyManager 在选择 API 密钥时，会优先考虑与当前命中缓存相关联的密钥，以提高缓存利用效率。
  • 核心缓存逻辑: CacheManager (app/core/cache/manager.py) 提供了缓存创建、查找、删除等核心服务接口。
  • SDK 兼容性: GeminiClient (app/core/services/gemini.py) 已适配 google-generativeai==0.8.5 SDK 版本，并支持在 API 调用中传递 cached_content_id 参数以利用原生缓存。
  • 统计与报告: 项目的报告系统 (app/core/reporting/reporter.py) 和使用追踪模块 (app/core/tracking.py) 已更新，能够准确记录并展示缓存命中率以及通过缓存节省的 Token 数量等信息。

• API 密钥智能选择与错误处理 (app/core/keys, app/core/processing)

  • Token 预检查: APIKeyManager 的 select_best_key 方法在选择 Key 前会进行 Token 预估和检查，避免因超出 Key 的 TPM 限制而导致的直接失败。
  • 高级轮转策略: 引入基于“上次使用时间”的轮转机制，在评分相近的可用 Key 中优先选择最近最少使用的，进一步优化负载均衡。
  • 选择过程追踪: APIKeyManager 现在会详细记录 Key 选择过程中的筛选原因，并在报告页面 (/manage/report) 中展示，便于问题诊断和策略优化。
  • 精细化错误处理: app/core/processing/error_handler.py 优化了对各类 API 错误的响应：
    • 5xx 错误：临时标记受影响的 Key 并触发重试。
    • 429 错误：区分每日配额耗尽（永久标记当日耗尽并重试其他 Key）和普通速率限制（临时标记 Key）。
    • 401/403/400 (Key 无效)：标记 Key 并通常不进行重试。
  • 流式请求错误隔离: 流式请求内部发生的错误将不再触发外层的 Key 重试逻辑。
  • 动态上下文截断: app/core/processing/utils.py 中的 truncate_context 函数会根据选定 Key 的实时可用 Token 容量和模型静态限制动态调整上下文长度。
  • 按 Key 配置上下文: Web UI (/manage/keys) 允许在数据库模式下为每个 API Key 单独配置是否启用传统上下文补全。

• 多模态图像输入 (inline_data) 支持:

  • 请求转换: app/core/context/converter.py 中的 convert_messages 函数已增强，能够正确处理 OpenAI API 格式消息中通过 image_url (Base64 Data URI) 提供的图像数据，并将其转换为 Gemini API 所需的 inline_data 格式。
  • API 模型与客户端兼容: app/api/models.py 中定义的请求/响应模型以及 app/core/services/gemini.py 中的 Gemini 客户端均已适配处理多模态数据。
  • 上下文存储:
    • app/core/context/store.py 在序列化和反序列化JSON数据时，能够存储和加载包含 inline_data 的上下文结构。
    • 然而，store.py 内部用于在不同消息格式间转换的辅助函数（例如，从 Gemini 格式转换为数据库存储格式的 convert_gemini_to_storage_format）对 inline_data 的处理尚不完整，可能导致在特定转换场景下图像信息丢失。核心的请求到Gemini API的转换由 converter.py 处理。

• Web UI 体验增强:

  • 新增了网站图标 (assets/favicon.ico)。
  • 对多个管理页面 (manage_context.html, manage_keys.html, manage.html, report.html) 及基础模板 (_base.html) 进行了界面和交互优化。

• 代码架构与质量提升:

  • 深度重构: 核心业务逻辑已全面迁移至 app/core/ 下的细分功能模块（如 database, keys, cache, context, services, processing, reporting, security, utils），显著提升了代码的组织性和模块化程度。
  • 模块化: 原有的大型文件（如旧的 app/api/request_processing.py）已被拆分为更小、职责更单一的模块。
  • 依赖清晰: 全面审查并更新了项目中的 import 语句，确保路径准确，优先使用绝对导入。
  • 代码清理: 移除了大量已迁移、废弃或冗余的代码和文件。
  • 本地化: 为重构和新增的核心 Python 文件添加了全面的中文注释，便于理解和维护。

• 关键错误修复:

  • 解决了重构过程中引入的多个 ImportError 和 NameError。
  • 优化了数据库文件路径处理逻辑 (app/core/database/utils.py)：优先判断是否使用内存数据库（基于 HF_SPACE_ID, APP_DB_MODE, config.KEY_STORAGE_MODE）；若使用文件数据库，则默认尝试在用户主目录下的 ~/.gemini_api_proxy/data/ 创建，并在失败时回退到内存模式。这改善了应用在不同环境下启动时因数据库文件访问问题导致的错误。
  • 修复了与 SQLAlchemy 2.0 版本兼容性相关的问题。

• 项目配置与文档:

  • 模型限制: 创建并要求配置 app/data/model_limits.json 文件，用于定义各模型的速率和 Token 限制。
  • 环境变量: 更新了 .env.example (或 .env 示例部分在 readme.md)，包含了新功能和配置相关的环境变量。
  • 依赖更新: requirements.txt 已更新，例如明确使用 google-generativeai==0.8.5。
  • 文档同步: readme.md 已根据最新功能和配置进行全面更新。