# AI-Cache

**Repository Path**: xcmrfc-thanos/AI-Cache

## Basic Information

- **Project Name**: AI-Cache
- **Description**: AI-Cache，自用，省钱
- **Primary Language**: Go
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-21
- **Last Updated**: 2026-06-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI-Cache

纯 Go 实现的 GPT / Claude API 缓存网关，对接 [New API](https://github.com/Calcium-Ion/new-api) 上游，提供三层缓存（FreeCache → Redis Cluster → SQLite）与 token 统计。

**仓库**：https://gitee.com/xcmrfc-thanos/AI-Cache

## 架构

同一 `AI-Cache.exe` 通过不同配置文件启动两个实例，共享 Redis、独立 SQLite 与缓存键前缀：

```
OpenAI SDK  → AI-Cache (:8080, mode=gpt)    → New API /v1/chat/completions …
Claude Code → AI-Cache (:8081, mode=claude) → New API /v1/messages
                         ↓
              FreeCache → Redis Cluster → SQLite
```

| 实例 | 端口 | 配置 | 键前缀 |
|------|------|------|--------|
| GPT | `:8080` | `configs/gpt.yaml` | `gpt_cache:` |
| Claude | `:8081` | `configs/claude.yaml` | `claude_cache:` |

`server.mode`（`gpt` / `claude`）决定注册哪套路由；省略时按 `service_name` 或 `key_prefix` 自动推断。

## 快速开始

### 1. 获取代码

```bash
git clone https://gitee.com/xcmrfc-thanos/AI-Cache.git
cd AI-Cache
```

### 2. 配置

编辑 `configs/gpt.yaml` 与 `configs/claude.yaml`，完整示例见 `configs/config.example.yaml`。

> 含真实密钥的配置请勿提交 Git；可本地复制为 `configs/gpt.local.yaml` 等并使用 `-config` 指定。

**server**

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `mode` | 自动推断 | 实例类型：`gpt` 注册 OpenAI 路由，`claude` 注册 Anthropic 路由；省略时按 `service_name` 或 `cache.key_prefix` 推断 |
| `addr` | `:8080` | HTTP 监听地址 |
| `service_name` | `gpt-cache` / `claude-cache` | 日志与健康检查中的服务名 |
| `access_log` | `true` | 是否记录 HTTP 访问日志（`/health` 除外） |

**upstream**

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `base_url` | — | New API 根地址；GPT / Claude 实例共用；可写 `https://host` 或 `https://host/v1`，程序统一拼 `/v1/...` |
| `api_key` | — | 上游 API Key |
| `timeout_sec` | `180` | 上游 HTTP 超时（秒） |
| `auth_mode` | 有 key 时为 `fixed` | `fixed`：始终用配置中的 `api_key` 访问上游，客户端 Authorization 可随意；`passthrough`：转发客户端 Authorization |

**redis**

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `addrs` | — | Redis Cluster 种子节点列表（至少 3 个主节点地址，如 `127.0.0.1:7001`） |
| `username` | — | ACL 用户名（应用账号，如 `pufa_app`） |
| `password` | — | ACL 密码；不可用时不写 Redis，降级 L1 + SQLite |

**sqlite**

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `path` | `./data/cache.db` | SQLite 文件路径；GPT / Claude 实例须各用独立文件 |

**cache**

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `key_prefix` | `gpt_cache:` | 缓存键前缀；GPT 与 Claude 实例必须不同，避免键冲突 |
| `local_mb` | `256` | L1 FreeCache 内存上限（MB） |
| `local_ttl_sec` | `600` | L1 条目 TTL（秒） |
| `redis_max_blob_kb` | `64` | gzip 后响应超过此大小时不写 Redis，仅 L1 + SQLite |
| `models` | 内置白名单 | 可缓存模型列表；请求模型名须命中白名单（支持前缀匹配，如 `gpt-5.4-20260201` 匹配 `gpt-5.4`） |

**token**

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `max_input` | `6000` | 输入 token 估算值 ≥ 此阈值时不缓存 |

**model_aliases**（YAML 顶层，与 `server` 同级）

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `model_aliases` | `{}` | 客户端模型名 → 白名单基准名映射；用于缓存键与白名单校验，例如 `my-gpt: gpt-5.4` |

**context**

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `slide_window.enabled` | `false` | 转发上游前是否裁剪 messages / input 历史 |
| `slide_window.keep_rounds` | `5` | 保留最近 N 轮 user/assistant 对话；全部 `system` 固定保留在头部 |
| `slide_window.apply_to_cache` | `true` | 网关缓存 Key 是否基于裁剪后内容生成 |
| `normalize.enabled` | `false` | Prompt 归一化（空白、中文标点） |
| `token_limit.enabled` | `false` | 转发前 token 硬截断 |
| `token_limit.max_input` | `6000` | 转发 token 上限（默认同 `token.max_input`） |
| `fixed_system.enabled` | `false` | 固定 system 前缀 |
| `fixed_system.mode` | `replace` | `replace` 替换客户端 system；`reject` 不一致时 400 |
| `fixed_system.content` | — | 固定 system 文本 |
| `session_sticky.enabled` | `false` | 会话粘性上游路由 |
| `session_sticky.header` | — | 会话 ID HTTP 头（如 `X-Session-Id`） |
| `session_sticky.field` | `user` | 无 header 时从 JSON 字段读取 |
| `session_sticky.upstreams` | `[]` | 上游节点列表（哈希选路） |
| `continuation.enabled` | `false` | 接续类提问短 TTL |
| `continuation.keywords` | 内置 | 关键词列表 |
| `continuation.short_ttl_sec` | `600` | 短 TTL 秒数 |

Redis Cluster 本地部署见分支 `docs/redis-deploy` 中的 `deploy/redis-6.2.18-win64-cluster/`。

### 3. 编译运行

```bash
build.bat
# 或：go build -o bin/AI-Cache.exe ./cmd/server

bin/AI-Cache.exe -config configs/gpt.yaml
bin/AI-Cache.exe -config configs/claude.yaml
```

> `github.com/mattn/go-sqlite3` 需要 CGO，Windows 需安装 GCC（如 MinGW）。

重新编译前请先停止正在运行的实例（`Ctrl+C` 或 `taskkill /IM AI-Cache.exe /F`），否则 exe 会被占用无法覆盖。

### 4. 客户端配置

**GPT / Codex（OpenAI SDK）：**

```python
from openai import OpenAI
client = OpenAI(base_url="http://127.0.0.1:8080/v1", api_key="any")
```

**Claude Code：**

```bash
export ANTHROPIC_BASE_URL=http://127.0.0.1:8081
```

## API

**GPT 实例（mode=gpt）**

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/v1/chat/completions` | Chat（带缓存） |
| POST | `/v1/completions` | Completions / Codex（带缓存） |
| POST | `/v1/responses` | Responses API（带缓存，流式支持命中回放） |
| GET | `/health` | 健康检查 |
| GET | `/stats/today` | 当日统计快照 |

**Claude 实例（mode=claude）**

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/v1/messages` | Anthropic Messages（带缓存） |
| GET | `/health` | 健康检查 |
| GET | `/stats/today` | 当日统计快照 |

## 缓存规则

仅当 **同时满足** 以下条件时写入/读取缓存：

- 模型在 `cache.models` 白名单内
- `temperature=0` 且 `top_p=1`
- `presence_penalty=0` 且 `frequency_penalty=0`（未传视为 0）
- 无 tools / tool_choice / function_call / 图片输入
- 输入 token < `token.max_input`（默认 6000）
- `stop` / `stop_sequences` 参与缓存键隔离，允许缓存（temp=0 下同键输出一致）
- 流式请求全路由支持读缓存并 SSE 回放；流式 miss 收完后异步写入，下次流式/非流式均可命中

## 三层缓存

| 层级 | 存储 | TTL（示例） |
|------|------|-------------|
| L1 | FreeCache（`cache.local_mb`） | `cache.local_ttl_sec` |
| L2 | Redis Cluster | mini/haiku: 3h；gpt-4/5、claude: 1h |
| L3 | SQLite | mini/haiku: 7d；gpt-4/5、claude: 12h |

- 首次 miss 仅写 SQLite；L3 命中 ≥2 次且 blob ≤ `redis_max_blob_kb` 才晋升 Redis
- 全部响应 gzip 压缩存储
- Redis 不可用时降级为 L1 + SQLite；SQLite 不可用时降级为 L1-only

## 项目结构

```
cmd/server/main.go          # 唯一入口
pkg/bootstrap/              # 初始化、路由注册、优雅退出
internal/handler/           # GPT 路由
internal/claude/            # Claude 路由与上游代理
internal/proxy/             # GPT 上游转发
internal/cache/             # 三层缓存核心
internal/stats/             # 内存统计 + 每小时刷盘
internal/store/             # SQLite / Redis
internal/token/             # Token 估算
internal/context/           # 滑动窗口裁剪
internal/worker/            # 过期数据清理
configs/gpt.yaml
configs/claude.yaml
configs/config.example.yaml
docs/DESIGN.md
docs/需求.md
build.bat
```

详细设计见 [docs/DESIGN.md](docs/DESIGN.md)。