qc0624/api-proxy repository overview

⁠API Cache Proxy

OpenAI 到 Claude API 的代理服务，支持请求格式自动转换、Prompt Caching 优化、多渠道负载均衡和 Web 管理界面。

⁠✨ 核心特性

• 🔄 OpenAI API 兼容：完全兼容 OpenAI SDK，无缝切换到 Claude
• ⚡ Prompt Caching：自动注入缓存标记，降低 API 成本 50-90%
• 🧠 Extended Thinking：支持 Claude 深度思考模式
• 🎯 多渠道管理：优先级负载均衡，自动故障转移
• 📊 Web 管理界面：实时统计、日志追踪、渠道配置
• 📱 PWA 支持：可安装到桌面和移动设备
• 💾 数据持久化：SQLite 存储配置和日志

⁠🚀 快速开始

⁠Docker Run

docker run -d \
  --name api-cache-proxy \
  -p 9090:9090 \
  -v $(pwd)/data:/data \
  -e TZ=Asia/Shanghai \
  qc0624/api-proxy:latest

⁠Docker Compose（推荐）

创建 docker-compose.yml：

services:
  api-cache-proxy:
    image: qc0624/api-proxy:latest
    container_name: api-cache-proxy
    restart: unless-stopped
    ports:
      - "9090:9090"
    volumes:
      - ./data:/data
    environment:
      - TZ=Asia/Shanghai
      - TARGET_API=https://api.anthropic.com
      - DEFAULT_MODEL=claude-sonnet-4-20250514

启动服务：

docker-compose up -d

⁠访问管理界面

打开浏览器访问：http://localhost:9090

• 统计仪表板：实时查看 Token 用量、缓存命中率
• 渠道管理：配置多个 Claude API 密钥，实现负载均衡
• 配置管理：设置 API Key 认证、缓存策略等

⁠📖 使用示例

⁠使用 OpenAI Python SDK

from openai import OpenAI

# 指向代理服务
client = OpenAI(
    base_url="http://localhost:9090/v1",
    api_key="your-api-key"  # 如果启用了认证
)

# 像使用 OpenAI 一样使用
response = client.chat.completions.create(
    model="claude-sonnet-4-20250514",
    messages=[
        {"role": "user", "content": "Hello!"}
    ]
)

print(response.choices[0].message.content)

⁠使用 cURL

curl -X POST http://localhost:9090/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

⁠流式响应

stream = client.chat.completions.create(
    model="claude-sonnet-4-20250514",
    messages=[{"role": "user", "content": "Count to 10"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

⁠⚙️ 环境变量

⁠🎯 核心功能

⁠1. 自动格式转换

自动将 OpenAI 请求格式转换为 Claude 格式：

• 模型映射：gpt-4 → claude-sonnet-4-20250514
• 消息格式：OpenAI messages → Claude messages + system
• 图片支持：image_url → Claude image format
• 流式响应：完整兼容 OpenAI SSE 格式

⁠2. Prompt Caching 优化

自动在长对话中注入缓存断点，降低成本：

• 首次请求：完整计费
• 后续请求：缓存命中部分仅收取 10% 费用
• 节省成本：长对话可节省 50-90% 费用

配置项：

• max_cache_blocks：最多缓存断点数（默认 4）
• cache_threshold_default：默认缓存阈值 800 字符
• cache_threshold_opus：Opus 模型阈值 16000 字符

⁠3. 多渠道负载均衡

• 配置多个 Claude API 密钥
• 按优先级和权重分配请求
• 自动故障转移
• 实时统计请求/错误计数

⁠4. Extended Thinking

支持 Claude 的深度思考模式：

response = client.chat.completions.create(
    model="claude-sonnet-4-20250514",
    messages=[{"role": "user", "content": "Solve this complex problem..."}],
    extra_body={
        "thinking": True,
        "thinking_budget": 10000
    }
)

⁠📱 PWA 功能

Web 管理界面支持 PWA（渐进式 Web 应用）：

• 可安装到桌面和移动设备主屏幕
• 离线访问缓存资源
• 自动更新检测
• 移动端优化（响应式布局、安全区域适配）

安装方式：

• Desktop：浏览器地址栏右侧点击安装图标
• iOS：Safari → 分享 → 添加到主屏幕
• Android：Chrome → 菜单 → 添加到主屏幕

⁠🔧 管理界面功能

⁠统计页面 (/stats)

• 请求数、成功率、Token 用量
• 缓存命中率统计
• 最近请求日志
• 服务运行时长

⁠日志页面 (/logs)

• 详细请求记录
• Token 用量可视化
• 缓存命中指示
• 错误信息追踪

⁠渠道管理 (/channels)

• 添加/编辑/删除渠道
• 配置优先级和权重
• 测试连通性
• 查看统计数据

⁠配置页面 (/config)

• API Key 认证设置
• 缓存策略配置
• Extended Thinking 设置
• 自定义模型管理

⁠🔐 API Key 认证

在配置页面启用 API Key 认证后，客户端需要提供密钥：

# 在管理界面生成随机 API Key（sk-xxx 格式）
# 或手动设置自定义密钥

# 客户端使用
curl -H "Authorization: Bearer your-api-key" \
  http://localhost:9090/v1/chat/completions

⁠🌐 兼容的工具

支持所有使用 OpenAI SDK 的工具和应用：

• LangChain - 设置 openai_api_base
• LlamaIndex - 设置 api_base
• Continue.dev - VSCode/JetBrains AI 助手
• Cursor - AI 代码编辑器
• Chatbox - 桌面聊天客户端
• OpenAI Playground - 修改 API 端点

⁠📦 数据持久化

数据存储在 SQLite 数据库中（通过 volume 挂载）：

• 配置信息（API Key、缓存策略等）
• 渠道列表
• 请求日志（最近 1000 条）
• 全局统计数据

备份数据：

# 数据库文件位置
./data/proxy.db

# 备份
cp ./data/proxy.db ./data/proxy.db.backup

⁠🔍 健康检查

# 健康检查端点
curl http://localhost:9090/health

# 获取统计数据
curl http://localhost:9090/api/stats

# 获取模型列表
curl http://localhost:9090/v1/models

⁠📝 更新日志

⁠v2.0.2 (2025-12)

• 优化缓存策略：缓存倒数第2条消息（原倒数第3条）
• 降低最小缓存触发消息数：2条消息即可触发（原需3条）
• 更快的缓存命中和成本节省

⁠v2.0.1 (2025-12)

• 完整的 Docker Hub 发布版本
• 优化的 .dockerignore 配置
• 修复默认配置为官方 API 地址

⁠v1.8 (2025-12)

• 深色模式蓝黑主题优化
• 所有交互元素蓝色发光效果
• 样式代码清理和统一

⁠v1.7 (2025-12)

• UI 框架迁移至 Vuetify 3
• 图标库切换到 Lucide Icons
• 大圆角设计和流畅动画

⁠📄 License

MIT License

⁠🤝 贡献

欢迎提交 Issue 和 Pull Request！

⁠📮 问题反馈

如有问题或建议，请在 GitHub 提交 Issue。