Skip to content

7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.

TypeScript

docs(i18n): translate install.md and api.md into zh-CN (#690)

Tashfeen3ea33cbc91ad
diff --git a/docs/api.md b/docs/api.md
index 262ad4e4..f0fe1ca9 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](i18n/zh-CN/docs/api.md)
+
# API reference
[← Back to README](../README.md) · [Documentation index](README.md)
diff --git a/docs/i18n/README.md b/docs/i18n/README.md
index 6f68c50b..f91d5de7 100644
--- a/docs/i18n/README.md
+++ b/docs/i18n/README.md
@@ -31,8 +31,8 @@ too.
| --- | --- |
| `README.md` | ✅ |
| `docs/README.md` | ✅ |
-| `docs/install.md` | English |
-| `docs/api.md` | English |
+| `docs/install.md` | ✅ |
+| `docs/api.md` | ✅ |
| `docs/clients.md` | English |
| `docs/compression.md` | English |
| `docs/architecture.md` | English |
diff --git a/docs/i18n/zh-CN/README.md b/docs/i18n/zh-CN/README.md
index e6a8dca0..f3d9715d 100644
--- a/docs/i18n/zh-CN/README.md
+++ b/docs/i18n/zh-CN/README.md
@@ -46,9 +46,9 @@
- [参与贡献](#参与贡献)
- [免责声明](#免责声明)
-**指南:** [安装与部署](../../install.md) · [API 参考](../../api.md) · [客户端与编程智能体](../../clients.md) · [提示词压缩](../../compression.md) · [架构与内部实现](../../architecture.md) · [文档索引](docs/README.md) · [贡献者指南](../../../CONTRIBUTING.md)
+**指南:** [安装与部署](docs/install.md) · [API 参考](docs/api.md) · [客户端与编程智能体](../../clients.md) · [提示词压缩](../../compression.md) · [架构与内部实现](../../architecture.md) · [文档索引](docs/README.md) · [贡献者指南](../../../CONTRIBUTING.md)
-> 以上指南目前只有英文版。中文版覆盖情况见 [翻译状态](../README.md#status)。
+> 「安装与部署」和「API 参考」已有中文版。「客户端与编程智能体」「提示词压缩」「架构与内部实现」目前只有英文版,上面的链接直接指向英文原文。完整的翻译状态见 [这里](../README.md#status)。
## 为什么会有这个项目
@@ -141,10 +141,10 @@
![功能概览](../../../repo-assets/features.png)
-- **OpenAI 的全部接口** —— `/v1/chat/completions`、`/v1/responses`(Codex CLI 需要它)、`/v1/completions`(编辑器的幽灵文本补全)、`/v1/images/generations`、`/v1/audio/speech`、`/v1/embeddings` 和 `/v1/models`,流式与非流式均可,来自官方 SDK 或任何 OpenAI 兼容客户端都行。[API 参考 →](../../api.md)
-- **Anthropic Messages API** —— `/v1/messages` 在同一套路由之上讲 Anthropic 的协议,所以 **Claude Code** 和官方 Anthropic SDK 可以直接跑在你的免费池上。[详情 →](../../api.md#anthropic--claude-clients)
+- **OpenAI 的全部接口** —— `/v1/chat/completions`、`/v1/responses`(Codex CLI 需要它)、`/v1/completions`(编辑器的幽灵文本补全)、`/v1/images/generations`、`/v1/audio/speech`、`/v1/embeddings` 和 `/v1/models`,流式与非流式均可,来自官方 SDK 或任何 OpenAI 兼容客户端都行。[API 参考 →](docs/api.md)
+- **Anthropic Messages API** —— `/v1/messages` 在同一套路由之上讲 Anthropic 的协议,所以 **Claude Code** 和官方 Anthropic SDK 可以直接跑在你的免费池上。[详情 →](docs/api.md#anthropic-与-claude-客户端)
- **原生 Gemini 与 Ollama 接口** —— Gemini CLI 可以用 `/v1beta`(`generateContent`、流式、词元计数、模型列表);可选的 Ollama 模拟则为 Zed、JetBrains 以及其他本地模型客户端提供 NDJSON 的 chat/generate、标签、元数据和嵌入。
-- **Fusion(多模型合成)** —— 请求虚拟模型 `fusion`,路由器会把你的提示词并行分发给一组风格各异的免费模型,再由一个评审模型从这些草稿中合成出一个答案。[详情 →](../../api.md#fusion-multi-model-synthesis)
+- **Fusion(多模型合成)** —— 请求虚拟模型 `fusion`,路由器会把你的提示词并行分发给一组风格各异的免费模型,再由一个评审模型从这些草稿中合成出一个答案。[详情 →](docs/api.md#fusion-多模型合成)
- **图像生成与文本转语音** —— `/v1/images/generations` 和 `/v1/audio/speech` 会在提供媒体模型的提供方之间路由,也包括自定义的 OpenAI 兼容媒体端点。
- **工具调用与结构化输出** —— OpenAI 风格的 `tools` 可在各提供方之间往返(纯文本形式的工具调用会被救回成真正的 `tool_calls`),另有 `response_format`、`seed`、`logprobs`、惩罚项以及其余采样参数按提供方透传。
- **智能路由,六种策略** —— 实时的每模型速度、能力、稳定性评分决定你的链路顺序;遇到 429/5xx 时自动转移到下一个模型,并带冷却和密钥轮换。[路由详解 →](../../architecture.md#routing-in-detail)
@@ -156,7 +156,7 @@
- **密钥加密存储,对外只有一个令牌** —— 提供方密钥以 AES-256-GCM 加密存放在 SQLite 中,每次请求时在内存里解密;你的应用自始至终只看到一个统一的 `freellmapi-…` bearer 令牌。
- **管理仪表盘与分析** —— React 界面用来管理密钥、调整链路顺序、使用试验台,并查看 24 小时到 90 天窗口的 p50/p95/首个词元用时分析;带登录保护,支持明暗主题和 [60 种语言](#语言)。
- **MCP 服务与交互式文档** —— 智能体可以通过 `/mcp` 查询可用模型、提供方健康状况和路由策略;`/v1/docs` 提供一个零依赖的 OpenAPI 浏览器。[编程智能体 →](../../clients.md)
-- **运维上的便利** —— 可选的响应缓存、加密的数据库备份、定期密钥健康检查、密钥批量导入导出、声明式启动配置。[安装与部署 →](../../install.md)
+- **运维上的便利** —— 可选的响应缓存、加密的数据库备份、定期密钥健康检查、密钥批量导入导出、声明式启动配置。[安装与部署 →](docs/install.md)
- **能跑 Node 20+ 的地方都能跑** —— Windows、macOS、Linux 服务器,或者一块小小的 ARM 单板机(树莓派也行)。在 PM2 / systemd 或你惯用的守护进程下,空闲时常驻内存约 40 MB。
项目范围是刻意收窄的,参见 [尚不支持的部分](../../architecture.md#not-yet-supported)。
@@ -175,7 +175,7 @@ curl -fsSL https://freellmapi.co/install.sh | bash
在 Windows 上,最省事的方式是下面提到的桌面版 **[Releases 里的 `.exe` 安装包](https://github.com/tashfeenahmed/freellmapi/releases/latest)**。Android 上可参考实验性的 [Termux 指南](../../install/android-termux.md)。
-其余内容,包括 Docker Compose、本地开发、声明式启动配置、生产构建、局域网访问和备份,都在 **[docs/install.md](../../install.md)**。
+其余内容,包括 Docker Compose、本地开发、声明式启动配置、生产构建、局域网访问和备份,都在 **[docs/install.md](docs/install.md)**。
## 桌面应用
@@ -183,7 +183,7 @@ curl -fsSL https://freellmapi.co/install.sh | bash
![FreeLLMAPI 桌面应用](../../../repo-assets/desktop.png)
-**[从 Releases 下载](https://github.com/tashfeenahmed/freellmapi/releases/latest)** —— 每个版本都附带 macOS 的 `.dmg` 和 Windows 的 `.exe` 安装包。不需要注册账号或设置密码:你唯一需要的凭据就是托盘悬浮窗里的统一 API 密钥。从源码构建的步骤,以及数据存放位置,见 [docs/install.md](../../install.md#desktop-app)。
+**[从 Releases 下载](https://github.com/tashfeenahmed/freellmapi/releases/latest)** —— 每个版本都附带 macOS 的 `.dmg` 和 Windows 的 `.exe` 安装包。不需要注册账号或设置密码:你唯一需要的凭据就是托盘悬浮窗里的统一 API 密钥。从源码构建的步骤,以及数据存放位置,见 [docs/install.md](docs/install.md#桌面应用)。
## 兼容 OpenAI 的客户端
@@ -261,7 +261,7 @@ print(resp.choices[0].message.content)
print("Routed via:", resp.headers.get("x-routed-via"))
```
-流式、`auto:*` 路由策略、工具调用、视觉输入、Gemini 的 Google 搜索接地、嵌入,以及 Anthropic Messages 接口,连同各自的 curl 和 Python 示例,全都在 **[docs/api.md](../../api.md)**。每个响应都带一个 `X-Routed-Via: <平台>/<模型>` 头,你可以据此看出实际是哪家提供方处理的。
+流式、`auto:*` 路由策略、工具调用、视觉输入、Gemini 的 Google 搜索接地、嵌入,以及 Anthropic Messages 接口,连同各自的 curl 和 Python 示例,全都在 **[docs/api.md](docs/api.md)**。每个响应都带一个 `X-Routed-Via: <平台>/<模型>` 头,你可以据此看出实际是哪家提供方处理的。
## 截图
diff --git a/docs/i18n/zh-CN/docs/README.md b/docs/i18n/zh-CN/docs/README.md
index 337bf8f2..b44584e5 100644
--- a/docs/i18n/zh-CN/docs/README.md
+++ b/docs/i18n/zh-CN/docs/README.md
@@ -4,13 +4,13 @@
根目录的 [README](../README.md) 是产品总览,详细指南在这里。
-> **翻译状态:** 下列指南目前只有英文版,链接直接指向英文原文。中文版的覆盖情况见
-> [翻译状态](../../README.md#status)。想认领其中一篇,欢迎提 PR。
+> **翻译状态:** 「安装与部署」和「API 参考」已翻译成中文。其余三篇指南目前只有英文版,
+> 链接直接指向英文原文。完整状态见 [这里](../../README.md#status)。想认领其中一篇,欢迎提 PR。
## 指南
-- **[安装与部署](../../../install.md)** —— 快速开始、Docker Compose、本地开发、声明式启动配置、Docker 镜像、备份、桌面应用,以及你的数据存放在哪里。
-- **[API 参考](../../../api.md)** —— 聊天补全、`auto:*` 路由策略、流式、工具调用、视觉、Gemini 的 Google 搜索接地、嵌入、响应头,以及 Anthropic Messages 接口。
+- **[安装与部署](install.md)** —— 快速开始、Docker Compose、本地开发、声明式启动配置、Docker 镜像、备份、桌面应用,以及你的数据存放在哪里。
+- **[API 参考](api.md)** —— 聊天补全、`auto:*` 路由策略、流式、工具调用、视觉、Gemini 的 Google 搜索接地、嵌入、响应头,以及 Anthropic Messages 接口。
- **[客户端与编程智能体](../../../clients.md)** —— 兼容 OpenAI 的客户端,Claude Code / Codex CLI / Cline / Continue / Aider / opencode / Cursor 的配方,MCP 服务,编辑器补全,以及上下文交接。
- **[提示词压缩](../../../compression.md)** —— 请求侧的各种模式、安全保护、按请求的控制项、自定义工具输出过滤器、统计数据和预览 API。
- **[架构与内部实现](../../../architecture.md)** —— 路由器如何工作、路由与运维细节、哪些还不支持、诚实的局限性说明,以及各提供方的服务条款审查。
diff --git a/docs/i18n/zh-CN/docs/api.md b/docs/i18n/zh-CN/docs/api.md
new file mode 100644
index 00000000..6592f722
--- /dev/null
+++ b/docs/i18n/zh-CN/docs/api.md
@@ -0,0 +1,300 @@
+[English](../../../api.md) · **简体中文**
+
+# API 参考
+
+[← 返回 README](../README.md) · [文档索引](README.md)
+
+任何兼容 OpenAI 的客户端都能用(Anthropic / Claude 客户端也可以,见 [Anthropic 与 Claude 客户端](#anthropic-与-claude-客户端))。Base URL 为 `http://localhost:3001/v1`,统一密钥在仪表盘的密钥页获取。`GET /v1/docs` 提供一个覆盖所有代理端点的交互式 OpenAPI 浏览器;规范文件本身在 `GET /v1/openapi.json`。
+
+- [聊天补全](#聊天补全)
+- [路由策略 `auto:*`](#路由策略-auto)
+- [流式输出](#流式输出)
+- [工具调用](#工具调用)
+- [Gemini 的 Google 搜索接地](#gemini-的-google-搜索接地)
+- [原生 Gemini API](#原生-gemini-api)
+- [Ollama 模拟](#ollama-模拟)
+- [可撤销的 URL 令牌](#可撤销的-url-令牌)
+- [视觉与图像输入](#视觉与图像输入)
+- [图像生成与文本转语音](#图像生成与文本转语音)
+- [Fusion 多模型合成](#fusion-多模型合成)
+- [响应头](#响应头)
+- [嵌入](#嵌入)
+- [Anthropic 与 Claude 客户端](#anthropic-与-claude-客户端)
+
+## 聊天补全
+
+**Python**
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+ base_url="http://localhost:3001/v1",
+ api_key="freellmapi-your-unified-key",
+)
+
+resp = client.chat.completions.create(
+ model="auto", # 交给路由器挑选;也可以指定具体模型,例如 "gemini-2.5-flash"
+ messages=[{"role": "user", "content": "用一句话概括罗马的衰亡。"}],
+)
+print(resp.choices[0].message.content)
+print("Routed via:", resp.headers.get("x-routed-via"))
+```
+
+**curl**
+
+```bash
+curl http://localhost:3001/v1/chat/completions \
+ -H "Authorization: Bearer freellmapi-your-unified-key" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "model": "auto",
+ "messages": [{"role": "user", "content": "hi"}]
+ }'
+```
+
+## 路由策略 `auto:*`
+
+单写 `auto` 会走你当前生效的回退链。加个后缀可以只影响这一次请求,不用改仪表盘:
+
+- `auto:smart` —— 偏向智能评分最高的模型
+- `auto:fast` —— 偏向实测速度(吞吐和首字节时间)
+- `auto:cheap` —— 偏向省钱;目前和 `balanced` 是同一套权重(池子里的东西本来就都是免费的)
+- `auto:reliable` —— 偏向近期成功率
+- `auto:balanced` —— 默认权重(稳定性优先,速度和智能分摊剩下的部分)
+
+这些策略会对 **所有已启用的模型** 重新排序,忽略你的链路顺序。常见的同义写法也能识别(`auto:fastest`、`auto:speed`、`auto:smartest`、`auto:cheapest`、`auto:budget` 等等),整个模型字符串不区分大小写。
+
+```bash
+curl http://localhost:3001/v1/chat/completions \
+ -H "Authorization: Bearer freellmapi-your-unified-key" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "model": "auto:fast",
+ "messages": [{"role": "user", "content": "hi"}]
+ }'
+```
+
+`auto:<配置档名>` 会走某个具名配置档的链路,而不是当前生效的那条,这样不同工具可以通过同一把密钥使用不同的链路:
+
+```bash
+curl http://localhost:3001/v1/chat/completions \
+ -H "Authorization: Bearer freellmapi-your-unified-key" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "model": "auto:coding",
+ "messages": [{"role": "user", "content": "Write a binary search in Rust."}]
+ }'
+```
+
+配置档名写错会返回一个明确的 `400`,而不是悄悄退回默认行为。配置档就是具名的回退链(见 [功能](../README.md#功能)),在仪表盘里创建和切换;当前生效的那条就是单写 `auto` 会用的。
+
+## 流式输出
+
+```python
+stream = client.chat.completions.create(
+ model="auto",
+ messages=[{"role": "user", "content": "Stream me a haiku about SQLite."}],
+ stream=True,
+)
+for chunk in stream:
+ print(chunk.choices[0].delta.content or "", end="", flush=True)
+```
+
+## 工具调用
+
+传入 OpenAI 风格的 `tools` 和 `tool_choice`,助手的响应会原样经代理往返,和直连 OpenAI API 一模一样。多步流程(助手发出 `tool_calls` → 以 `tool` 角色回填结果 → 最终答案)在路由器能触达的每一家提供方上都能跑通。
+
+```python
+tools = [{
+ "type": "function",
+ "function": {
+ "name": "get_weather",
+ "description": "Get current weather for a city.",
+ "parameters": {
+ "type": "object",
+ "properties": {"city": {"type": "string"}},
+ "required": ["city"],
+ },
+ },
+}]
+
+# 1. 模型请求调用工具
+first = client.chat.completions.create(
+ model="auto",
+ messages=[{"role": "user", "content": "What's the weather in Karachi?"}],
+ tools=tools,
+ tool_choice="required",
+)
+call = first.choices[0].message.tool_calls[0]
+
+# 2. 你执行工具,把结果回填进去
+final = client.chat.completions.create(
+ model="auto",
+ messages=[
+ {"role": "user", "content": "What's the weather in Karachi?"},
+ first.choices[0].message,
+ {"role": "tool", "tool_call_id": call.id, "content": '{"temp_c": 32, "cond": "sunny"}'},
+ ],
+ tools=tools,
+)
+print(final.choices[0].message.content)
+```
+
+配合 `stream=True` 也可以,你会先收到一串 `delta.tool_calls` 分块,然后是一个 `finish_reason: "tool_calls"` 收尾。底层实现上,兼容 OpenAI 的提供方(Groq、Cerebras、Mistral、OpenRouter、GitHub Models、HuggingFace、Cloudflare、Cohere 兼容模式)会直接透传请求;发往 Gemini 的请求会被翻译成 Google 的 `functionDeclarations` / `functionResponse` 结构,响应再翻译回来。
+
+## Gemini 的 Google 搜索接地
+
+Google 的模型可以把答案锚定在实时的 Google 搜索结果上。由于 OpenAI 的协议格式没法表达这件事,你可以请求一个名为 `google_search` 的工具,Google 提供方会把它翻译成 Gemini 原生的接地工具。它可以单独发送,也可以和你正常的函数工具一起发送。
+
+```python
+resp = client.chat.completions.create(
+ model="gemini-2.5-flash", # 固定到某个 Google 模型,让请求路由到那里
+ messages=[{"role": "user", "content": "Who won the F1 race this weekend?"}],
+ tools=[{"type": "function", "function": {"name": "google_search", "parameters": {}}}],
+)
+print(resp.choices[0].message.content)
+```
+
+## 原生 Gemini API
+
+Gemini 系列 SDK 和 Gemini CLI 可以使用原生的 `/v1beta` 接口:
+
+- `GET /v1beta/models`
+- `GET /v1beta/models/{model}`
+- `POST /v1beta/models/{model}:generateContent`
+- `POST /v1beta/models/{model}:streamGenerateContent`(Gemini CLI 需要加 `?alt=sse`)
+- `POST /v1beta/models/{model}:countTokens`
+
+```bash
+curl "http://localhost:3001/v1beta/models/gemini-2.5-flash:generateContent" \
+ -H "x-goog-api-key: freellmapi-your-unified-key" \
+ -H "Content-Type: application/json" \
+ -d '{"contents":[{"role":"user","parts":[{"text":"hello"}]}]}'
+```
+
+像 `gemini-2.5-flash` 这样的 Gemini 模型名,是通过 Gemini 系列映射(密钥 → Gemini 模型映射)解析的,而不是直接查目录,所以它们会路由到 Auto,或者路由到你为每个系列固定的那个目录模型。直接写目录里的 id 也一样能用。
+
+`contents` 里的文本、内联数据、函数调用与响应、系统指令、函数声明、结构化 JSON 输出、生成控制参数和思考额度,都会翻译进同一套内部的聊天与回退流程。Bearer 认证同样可用。Gemini 的 `?key=` 查询参数只在 `/v1beta` 下被接受;建议优先用请求头,因为写在 URL 里的凭据会泄漏到历史记录和日志中。
+
+## Ollama 模拟
+
+这个需要主动开启的 Ollama 接口,在 `/api/*` 下实现了 tags、chat、generate、show、version、embed 以及旧版 embeddings。流式输出是 Ollama 兼容的 NDJSON。它默认为 `off`,可以在 **密钥 → 智能体** 里选择 `open-loopback` 或 `key-required`。open-loopback 模式会检查直连的套接字对端,所以桌面端的局域网访问不会在你不知情的情况下把它变成一个无身份验证的局域网端点。
+
+`/api/embeddings` 这个路径同时也归仪表盘所有。带着有效仪表盘会话的请求会交给仪表盘处理;其他所有打到这个确切路径的请求都被当作 Ollama 的旧版 embeddings,按上面的模拟策略处理。
+
+## 可撤销的 URL 令牌
+
+无法发送请求头的客户端,可以在 `/v1/t/{token}/…` 下访问模型列表、聊天补全、Responses,以及 Ollama 风格的 chat 和 tags。这些令牌是随机生成的,只以哈希形式存储,可以单独撤销,并且不是那把统一密钥。在 **密钥 → 智能体** 里创建和撤销它们。
+
+即便如此也请把它们当作敏感信息:URL 常常会被 shell 历史、反向代理、浏览器历史和遥测数据留存下来。撤销是立即生效的。
+
+## 视觉与图像输入
+
+用标准的 OpenAI `image_url` 内容块发送图片(base64 的 `data:` URL 或者 `http(s)` URL 都行)。当请求里含有图片时,路由器会把自己限制在 **具备视觉能力的模型** 上,忽略纯文本模型。视觉模型在回退链页面上带有 **Vision** 标记;当前这批包括 Gemini(2.5 / 3.x)、Llama 4 Scout/Maverick(Groq、NVIDIA)、GLM-4.6V Flash(Z.ai)、Nemotron Nano 12B VL(OpenRouter),以及 GitHub 的 GPT-4o / GPT-4.1。
+
+```python
+resp = client.chat.completions.create(
+ model="auto", # 自动路由到视觉模型
+ messages=[{
+ "role": "user",
+ "content": [
+ {"type": "text", "text": "What's in this image?"},
+ {"type": "image_url", "image_url": {"url": "data:image/png;base64,<...>"}},
+ ],
+ }],
+)
+print(resp.choices[0].message.content)
+```
+
+如果你的回退链里没有启用任何具备视觉能力的模型,带图片的请求会返回一个明确的 `422`(`code: "no_vision_model"`),而不是悄悄把图片丢掉。(`/v1/responses` 上的图像输入目前还不支持,请改用 `/v1/chat/completions`。)
+
+## 图像生成与文本转语音
+
+`POST /v1/images/generations` 和 `POST /v1/audio/speech` 会在提供媒体模型的提供方之间路由,也包括自定义的 OpenAI 兼容媒体端点。可以在仪表盘的 **模型 → 图像 / 音频** 标签页里浏览和开关它们。
+
+## Fusion 多模型合成
+
+请求虚拟模型 `fusion`,路由器会把你的提示词并行分发给一组风格各异的免费模型,再由一个评审模型从这些草稿中合成出一个答案。参与的模型组、评审模型和策略都可以在仪表盘的 **Fusion** 页配置,也可以按请求通过 `fusion` 字段指定;每一次子调用都会正常走路由、额度和分析统计。
+
+## 响应头
+
+每个响应都带一个 `X-Routed-Via: <平台>/<模型>` 头,你可以据此看出每次调用实际是哪家提供方处理的。如果请求在提供方之间转移过,还会看到 `X-Fallback-Attempts: N`。
+
+HTTP 头只能携带可打印的 ASCII 字符,所以模型 id 里超出这个范围的字符(比如中转目录里的中文名称)在响应头中会被百分号编码。把这个值丢给 `decodeURIComponent`(或 `urllib.parse.unquote`)就能还原。
+
+可选开启的响应缓存能按请求用 `X-FreeLLM-Cache: on|off` 开关。它是一个针对完全相同的非流式请求做精确匹配的内存 LRU(以整个请求的规范化 SHA-256 为键,带 TTL 和温度门槛,节省量统计显示在仪表盘上)。默认关闭;缓存命中不消耗任何提供方额度。
+
+启用[提示词压缩](../../../compression.md)后,`X-FreeLLM-Compress: off|on|lossless|standard|aggressive` 可以对单次请求关闭或调低已配置的模式,但不能高于运维方配置的模式。响应会报告实际生效的模式和预估节省量,例如 `X-FreeLLM-Compress: standard; saved~=1840`。
+
+## 嵌入
+
+`/v1/embeddings` 兼容 OpenAI,但和聊天路由有一处刻意的区别:**故障转移绝不跨模型。** 不同模型产出的向量位于互不兼容的空间里,悄悄换个模型会污染建立在这个代理之上的任何向量库。所以嵌入是按 **系列**(一个模型身份加一个维度)路由的,故障转移只在服务于同一系列的提供方之间进行。
+
+```python
+resp = client.embeddings.create(
+ model="auto", # 默认系列;也可以写系列名,比如 "bge-m3"
+ input=["the quick brown fox", "pack my box with five dozen liquor jugs"],
+)
+print(len(resp.data), "vectors of", len(resp.data[0].embedding), "dims")
+```
+
+```bash
+curl http://localhost:3001/v1/embeddings \
+ -H "Authorization: Bearer freellmapi-your-unified-key" \
+ -H "Content-Type: application/json" \
+ -d '{"model": "auto", "input": "hello world"}'
+```
+
+`model` 接受 `auto`(配置好的默认系列)、某个系列名,或者某家提供方专属的模型 id(会解析到它所属的系列)。可用的系列:
+
+| 系列(`model`) | 维度 | 提供方(故障转移顺序) |
+| --- | --- | --- |
+| `gemini-embedding-001` *(默认)* | 3072 | Google |
+| `text-embedding-3-large` | 3072 | GitHub Models |
+| `text-embedding-3-small` | 1536 | GitHub Models |
+| `embed-v4.0` | 1536 | Cohere |
+| `bge-m3` | 1024 | Cloudflare → Hugging Face |
+| `qwen3-embedding-0.6b` | 1024 | Cloudflare |
+| `nv-embedqa-e5-v5` | 1024 | NVIDIA |
+| `llama-nemotron-embed-1b-v2` | 2048 | NVIDIA |
+| `llama-nemotron-embed-vl-1b-v2` | 2048 | NVIDIA → OpenRouter |
+| `embeddinggemma-300m` | 768 | Cloudflare |
+
+默认系列、各提供方的开关和优先级都在仪表盘的 **模型 → 嵌入** 页。为某个向量库选定一个系列之后就别再换了,这正是「系列」这个设计存在的意义。
+
+## Anthropic 与 Claude 客户端
+
+FreeLLMAPI 同样会讲 Anthropic 的 Messages API,所以任何为 Claude 写的东西,包括 **Claude Code** 和官方 Anthropic SDK,都能跑在你的免费池上。把客户端指向你服务器的 **根地址**(Anthropic 客户端会自己拼上 `/v1/messages`),用统一密钥认证即可。`x-api-key` 和 `Authorization: Bearer` 两种方式都接受。
+
+```bash
+curl http://localhost:3001/v1/messages \
+ -H "x-api-key: freellmapi-your-unified-key" \
+ -H "anthropic-version: 2023-06-01" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "model": "claude-sonnet-4-5",
+ "max_tokens": 256,
+ "messages": [{"role": "user", "content": "hi"}]
+ }'
+```
+
+Claude 的模型名在 **密钥 → Anthropic** 标签页里映射到你的免费池:每个系列(`default`、`opus`、`sonnet`、`haiku`)可以路由到 `auto`(由路由器挑一个免费模型),也可以固定到你指定的模型。`POST /v1/messages/count_tokens` 和一个按内容协商的 `GET /v1/models`(发送了 `anthropic-version` 时返回 Anthropic 的结构)也都实现了。流式、系统提示词、工具使用和图像输入,都经由和 OpenAI 端点相同的那套路由翻译。
+
+**Claude Code** —— 把它指向你的服务器再启动:
+
+*在 macOS / Linux 上(Bash):*
+```bash
+export ANTHROPIC_BASE_URL=http://localhost:3001
+export ANTHROPIC_AUTH_TOKEN=freellmapi-your-unified-key # 不是 ANTHROPIC_API_KEY
+claude
+```
+
+*在 Windows 上(PowerShell):*
+```powershell
+$env:ANTHROPIC_BASE_URL="http://localhost:3001"
+$env:ANTHROPIC_AUTH_TOKEN="freellmapi-your-unified-key"
+claude
+```
+
+> 请用 `ANTHROPIC_AUTH_TOKEN`(作为 Bearer 令牌发送),**不要**用 `ANTHROPIC_API_KEY`。Claude Code 会把已设置的 `ANTHROPIC_API_KEY` 当成互相冲突的第一方凭据,从而拒绝启动。
diff --git a/docs/i18n/zh-CN/docs/install.md b/docs/i18n/zh-CN/docs/install.md
new file mode 100644
index 00000000..1fca720e
--- /dev/null
+++ b/docs/i18n/zh-CN/docs/install.md
@@ -0,0 +1,229 @@
+[English](../../../install.md) · **简体中文**
+
+# 安装与部署
+
+[← 返回 README](../README.md) · [文档索引](README.md)
+
+把 FreeLLMAPI 跑起来所需的一切:一行命令、Docker Compose、本地开发、声明式配置、生产构建、桌面应用,以及你的数据存放在哪里。
+
+- [快速开始](#快速开始)
+- [Docker Compose](#docker-compose)
+- [本地开发](#本地开发)
+- [声明式启动配置](#声明式启动配置)
+- [Docker 镜像与运维](#docker-镜像与运维)
+- [桌面应用](#桌面应用)
+- [凭据与数据存放位置](#凭据与数据存放位置)
+
+## 快速开始
+
+需要 Docker。它会建好 `~/freellmapi`、生成加密密钥、拉取镜像并启动容器:
+
+```bash
+curl -fsSL https://freellmapi.co/install.sh | bash
+```
+
+不放心直接管道给 bash?[脚本在这里](https://freellmapi.co/install.sh)。重复执行是安全的:你的 `.env`(以及加密密钥)会被保留,容器会更新到 `:latest`。可以用 `FREELLMAPI_DIR`、`PORT` 或 `HOST_BIND` 环境变量覆盖默认值。
+
+在 Windows 上,最省事的方式是桌面版 **[Releases 里的 `.exe` 安装包](https://github.com/tashfeenahmed/freellmapi/releases/latest)**(见[下文](#桌面应用));上面的 Docker 步骤在 WSL 或任意 bash shell 里同样可用。
+
+在 Android 上,参见实验性的 [Termux 安装指南](../../../install/android-termux.md)。它使用 Node 内置的 SQLite 驱动,不需要 Android NDK。
+
+打开 http://localhost:3001 ,在 **密钥** 页添加你的提供方密钥,按喜好调整 **回退链** 的顺序,然后在 **密钥** 页顶部拿到你的统一 API 密钥。这个统一密钥就是你的 OpenAI SDK 要指向的东西。
+
+你的部署会自行从签名的目录源保持更新。当前的完整目录列在 [freellmapi.co/models](https://freellmapi.co/models.html)。
+
+## Docker Compose
+
+在 3001 端口上同时跑起 API 和仪表盘,并把 SQLite 持久化到一个具名卷里。
+
+**前置条件:** Docker、Docker Compose、OpenSSL。
+
+*在 macOS / Linux 上(Bash):*
+```bash
+git clone https://github.com/tashfeenahmed/freellmapi.git
+cd freellmapi
+
+# 生成用于静态存储密钥的加密密钥
+ENCRYPTION_KEY="$(openssl rand -hex 32)"
+printf "ENCRYPTION_KEY=%s\nPORT=3001\n" "$ENCRYPTION_KEY" > .env
+
+docker compose up -d
+```
+
+*在 Windows 上(PowerShell):*
+```powershell
+git clone https://github.com/tashfeenahmed/freellmapi.git
+cd freellmapi
+
+$Bytes = New-Object Byte[] 32
+[Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($Bytes)
+$ENCRYPTION_KEY = -join ($Bytes | ForEach-Object { "{0:x2}" -f $_ })
+"ENCRYPTION_KEY=$ENCRYPTION_KEY`nPORT=3001" | Out-File -Encoding utf8 .env
+docker compose up -d
+```
+
+> **想从另一台机器访问?** 默认情况下容器只发布在 `127.0.0.1` 上,所以从别的设备打开 `http://<服务器 IP>:3001` 是加载不出来的(页面会一直卡住)。想把它暴露到局域网,比如让树莓派在 `http://192.168.1.x:3001` 上可访问,就用 `HOST_BIND=0.0.0.0` 启动:
+>
+> ```bash
+> HOST_BIND=0.0.0.0 docker compose up -d
+> ```
+>
+> 只在你信任的网络里这么做:这个代理是单用户的,唯一的防护就是那把统一 API 密钥。
+
+## 本地开发
+
+**前置条件:** Node.js 20+、npm。
+
+*在 macOS / Linux 上(Bash):*
+```bash
+git clone https://github.com/tashfeenahmed/freellmapi.git
+cd freellmapi
+npm install
+ENCRYPTION_KEY="$(node -e 'console.log(require("crypto").randomBytes(32).toString("hex"))')"
+printf "ENCRYPTION_KEY=%s\nPORT=3001\n" "$ENCRYPTION_KEY" > .env
+npm run dev
+```
+
+*在 Windows 上(PowerShell):*
+```powershell
+git clone https://github.com/tashfeenahmed/freellmapi.git
+cd freellmapi
+npm install
+$ENCRYPTION_KEY = node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+"ENCRYPTION_KEY=$ENCRYPTION_KEY`nPORT=3001" | Out-File -Encoding utf8 .env
+npm run dev
+```
+
+启动必须要有 `ENCRYPTION_KEY`。当 `NODE_ENV` 不是 `production` 且没有设置它时,服务会自动生成一个开发用的密钥,并保存到 SQLite 数据库旁边的 `.encryption-key` 文件(权限 0600)里,而不是存进数据库。以前把密钥存在数据库里的旧安装,会在首次启动时迁移到这个文件。不要在放着真实提供方密钥的环境里依赖这个兜底行为,请显式设置 `ENCRYPTION_KEY`。
+
+请求分析数据默认保留 90 天或 100000 条请求记录,以先触发的那个上限为准。在 `.env` 里设置 `REQUEST_ANALYTICS_RETENTION_DAYS=0` 或 `REQUEST_ANALYTICS_MAX_ROWS=0` 可以分别关掉对应的保留上限。
+
+打开 http://localhost:5173 (Vite 开发界面),在 **密钥** 页添加你的提供方密钥,按喜好调整 **回退链** 的顺序,然后在 **密钥** 页顶部拿到你的统一 API 密钥。这个统一密钥就是你的 OpenAI SDK 要指向的东西。
+
+> **想从局域网里的另一台设备访问开发界面?** 用 `npm run dev:lan`。它会把 `--host` 透传给 Vite,Vite 随后会打印一个 `Network: http://<你的 IP>:5173` 的地址,你可以在手机或另一台机器上打开。(直接写 `npm run dev -- --host` 在这里*不*管用:根目录的 `dev` 脚本是一个 `concurrently` 包装器,这个参数根本传不到 Vite。)API 调用走 Vite 的开发代理,所以不需要额外的服务端配置。
+
+不用 Docker 的生产构建:
+
+```bash
+npm run build
+node server/dist/index.js # 服务和仪表盘都在 :3001 上提供
+```
+
+## 声明式启动配置
+
+为了让 Docker 或服务器安装可以重复复现,FreeLLMAPI 支持在每次启动时应用一份 JSON 配置。设置 `FREEAPI_CONFIG_PATH=/path/to/freellmapi.config.json`,或者把同样的 JSON 放进 `FREEAPI_CONFIG_JSON`。这份配置是幂等的:已存在的密钥、自定义提供方、模型改动、回退链条目和路由设置会被更新,而不是重复添加。
+
+```json
+{
+ "keys": [
+ { "platform": "groq", "key": "gsk_...", "label": "main" },
+ { "platform": "google", "key": "AIza...", "enabled": true }
+ ],
+ "customProviders": [
+ {
+ "baseUrl": "http://host.docker.internal:11434/v1",
+ "label": "Ollama",
+ "models": [
+ { "model": "llama3.1:8b", "displayName": "Local Llama", "supportsTools": true }
+ ]
+ }
+ ],
+ "models": [
+ {
+ "platform": "groq",
+ "modelId": "llama-3.3-70b-versatile",
+ "displayName": "Llama 3.3 70B",
+ "supportsTools": true,
+ "fallbackEnabled": true
+ }
+ ],
+ "routing": { "strategy": "balanced" }
+}
+```
+
+如果两个自定义端点提供同一个模型 id,请在 `models` 或 `fallback` 条目里加上 `"endpoint"` 来指明你说的是哪一个,填端点的 URL,或者仪表盘显示在它旁边的那个短标识。不加的话,一条能匹配到多个端点的条目会被直接拒绝,而不是随便挑一个应用:
+
+```json
+{
+ "models": [
+ { "platform": "custom", "modelId": "deepseek-v3.1", "endpoint": "https://relay-b.example.com/v1", "enabled": false }
+ ]
+}
+```
+
+## Docker 镜像与运维
+
+FreeLLMAPI 发布一个生产镜像,里面包含 Express 服务和构建好的 React 仪表盘:
+
+```bash
+docker pull ghcr.io/tashfeenahmed/freellmapi:latest # 也可以固定到某个版本,例如 :v1.2.3
+```
+
+镜像是多架构的(`linux/amd64` 和 `linux/arm64`,所以树莓派上也能跑)。发布的标签有:`latest`(默认分支)、`v*.*.*`(git 发布标签)和 `sha-<commit>`。
+
+仓库里自带的 `docker-compose.yml` 是推荐的安装方式:
+
+```bash
+docker compose up -d
+docker compose logs -f freellmapi
+```
+
+容器端口默认绑定在 `127.0.0.1`(仅本机)。想从网络里的另一台机器访问仪表盘或 API,用 `HOST_BIND=0.0.0.0 docker compose up -d` 把它发布到所有网卡上。只在可信的局域网里这么做,因为这个代理是单用户的。
+
+SQLite 数据存放在 `freellmapi-data` 卷的 `/app/server/data` 下。升级时请保持 `.env` 里的 `ENCRYPTION_KEY` 和这个卷不变,因为提供方密钥是加密存储的。如果你的宿主机只持久化某个特定目录,可以设置 `FREEAPI_DB_PATH=/that/path/freellmapi.db`。
+
+在磁盘不持久的宿主机上,配置一个加密备份目标:
+
+```env
+FREEAPI_DB_BACKUP_PATH=/app/server/data/freellmapi.db.backup
+# 或者:
+FREEAPI_DB_BACKUP_URL=https://example.com/freellmapi.db.backup
+FREEAPI_DB_BACKUP_TOKEN=optional-bearer-token
+FREEAPI_DB_BACKUP_KEY=64-char-hex-backup-key
+FREEAPI_DB_BACKUP_INTERVAL_MS=300000
+```
+
+启动时如果数据库文件不存在,FreeLLMAPI 会先恢复备份,再执行迁移。服务运行期间,它会定期上传一份新的加密备份。如果没有设置 `FREEAPI_DB_BACKUP_KEY`,备份信封也会使用 `ENCRYPTION_KEY`。
+
+更多 Docker 运维内容和示例在 [docker/README.md](../../../../docker/README.md)。
+
+## 桌面应用
+
+[`desktop/`](../../../../desktop) 里有一个原生的菜单栏应用:整个路由器加仪表盘就在你的托盘里本地运行,还有一个玻璃质感的悬浮窗显示实时请求统计。
+
+![FreeLLMAPI 桌面应用](../../../../repo-assets/desktop.png)
+
+**[从 Releases 下载](https://github.com/tashfeenahmed/freellmapi/releases/latest)** —— macOS 的 `.dmg` 和 Windows 的 `.exe` 安装包由 [`desktop-release`](../../../../.github/workflows/desktop-release.yml) 工作流在每个版本发布时构建并附带。你也可以花几分钟从本仓库自己构建:
+
+> **Windows 用户从源码构建的注意事项:** 构建桌面应用需要为 Electron 编译原生 SQLite 模块。在执行 `npm install` 之前,你必须先装好 [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)(具体来说是「使用 C++ 的桌面开发」工作负载)以及 Python。
+
+```bash
+npm install
+npm install --prefix desktop # 安装桌面端依赖
+npm run desktop:dist # macOS → desktop/dist-electron/FreeLLMAPI-…-arm64.dmg
+npm run desktop:dist:win # Windows → "desktop/dist-electron/FreeLLMAPI Setup ….exe"
+```
+
+> 本地构建出来的应用没有签名,所以 Windows SmartScreen 首次运行时可能会警告(点「更多信息」→「仍要运行」);macOS 构建则不会触发 Gatekeeper 提示。
+> 完整说明见 [desktop/README.md](../../../../desktop/README.md)。
+
+## 凭据与数据存放位置
+
+桌面应用 **不需要设置用户名或密码**。服务器版会用邮箱加密码的账号把仪表盘挡在登录后面,而桌面版不同:它用一个隐藏的本地账号自动登录仪表盘,所以你永远不会被要求输入凭据,也不需要有一个。
+
+你唯一需要的凭据是那把 **统一 API 密钥**,也就是你的 OpenAI/Anthropic 客户端要指向的 `freellmapi-…` 令牌。可以从这两个地方拿到:
+
+- 托盘悬浮窗:点击托盘图标,然后点 **复制密钥**;或者
+- 仪表盘 **密钥** 页的顶部(托盘 → **打开仪表盘**)。
+
+你不需要手动打开或编辑 `freeapi.db`。
+
+你的设置和数据按操作系统存放在一个文件夹里(迁移到另一台机器或搬进容器时,复制它就行):
+
+| 操作系统 | 位置 |
+|----|----------|
+| Windows | `%APPDATA%\FreeLLMAPI\`(例如 `C:\Users\<你>\AppData\Roaming\FreeLLMAPI\`) |
+| macOS | `~/Library/Application Support/FreeLLMAPI/` |
+| Linux | `~/.config/FreeLLMAPI/` |
+
+这个文件夹里有 `freeapi.db`(全部密钥、模型和设置,加密存储)和 `config.json`(窗口、主题、端口、局域网偏好)。搬迁安装时两个都要复制。对于服务器(非桌面)部署,对应的状态是 `.env` 文件和位于 `server/data/freeapi.db`(或者 `FREEAPI_DB_PATH` 指向的位置)的 SQLite 数据库。
diff --git a/docs/install.md b/docs/install.md
index 83e8abb1..6f6467f6 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -1,3 +1,5 @@
+**English** · [简体中文](i18n/zh-CN/docs/install.md)
+
# Install & deploy
[← Back to README](../README.md) · [Documentation index](README.md)