# @dotlab-hq/llm-proxy 中文文档

规范地址：https://npmcn.com/package/%40dotlab-hq/llm-proxy/

版本：1\.0\.12
npm 元数据更新时间：2026-05-03T17:43:13.869Z
中文译文更新时间：2026-11-12T20:42:58.007Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dotlab-hq/llm-proxy
原文对照：https://npmcn.com/package/%40dotlab-hq/llm-proxy/?lang=original
项目主页：https://github.com/dotlab-hq/llm-proxy#readme
源码仓库：https://github.com/dotlab-hq/llm-proxy

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2 MB，4 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：8 个
- peer 依赖：typescript ^5
- 首次发布：2026-05-01T21:20:11.760Z
- 最新版本发布：2026-05-03T17:43:13.557Z
- 近 30 天下载量：5182（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

LLM 语言 具有 OpenAI 兼容性的代理服务器

## 安装

```sh
npm install @dotlab-hq/llm-proxy
```

也可以使用：`pnpm add @dotlab-hq/llm-proxy`、`yarn add @dotlab-hq/llm-proxy`、`bun add @dotlab-hq/llm-proxy`

## README

# @dotlab-hq/llm-代理服务器

一个本地的 LLM API 代理服务器,其速率限制,缓存和多后端支持. 作为OpenAI兼容的API端点工作.

## 快速启动

### 1\. 初始化配置

创建新 `model.jsonc` 配置文件 :

```bash
npx @dotlab-hq/llm-proxy init
```

或者跳过自动提示 :

```bash
npx @dotlab-hq/llm-proxy init --skip-prompts
```

### 2\. 配置您的模型

编辑生成的 `model.jsonc` 并添加您的 LLM 提供者 :

```jsonc
{
  "$schema": "https://raw.githubusercontent.com/dotlab-hq/llm-proxy/refs/heads/main/schema.json",
  "state-adapter": "memory",
  "models": {
    "openai": [
      {
        "id": "primary-openai",
        "name": "Primary Instance",
        "models": ["gpt-3.5-turbo", "gpt-4"],
        "individualLimit": true,
        "baseUrl": "https://api.openai.com/v1",
        "apiKey": "sk-your-api-key-here",
        "rateLimit": {
          "tokensPerMinute": 90000,
          "requestsPerMinute": 3500,
          "requestsPerDay": 200000
        }
      }
    ]
  }
}
```

### 3\. 启动服务器

```bash
npx @dotlab-hq/llm-proxy serve
```

服务器从端口开始 **25789 (中文(简体) )** 默认。 如果忙, 它会自动选择下一个可用的端口 .

与 `--skip-prompts`,服务器立即启动,没有提示.

## CLI 命令

### `init`

初始化一个新的 `model.jsonc` 配置 :

```bash
npx @dotlab-hq/llm-proxy init
npx @dotlab-hq/llm-proxy init --skip-prompts
```

### `serve`

启动 LLM 代理服务器 :

```bash
npx @dotlab-hq/llm-proxy serve
npx @dotlab-hq/llm-proxy serve --skip-prompts
```

**它会做什么:**

-   装入配置从 `model.jsonc`
-   在端口25789上开始( 如果忙则自动选择下一个可用)
-   显示服务器配置细节
-   按 Ctrl+C 键停止

### 选项

-   `--skip-prompts` - 跳过所有交互式提示并使用默认

## 配置格式

### JSONC(载有评论的JSON)

配置使用 **约克** 更好的用户体验格式 :

-   ✅ 为文件保留了评论
-   \* 内在字段解释
-   显示示例值
-   \* 已记录的可选字段

### 动态Schema 参考

生成的 schema 引用总是指最近的版本 :

```jsonc
"$schema": "https://raw.githubusercontent.com/dotlab-hq/llm-proxy/refs/heads/main/schema.json"
```

当作为国家防范机制一揽子方案安装并在当地链接时,它提到:

```jsonc
"$schema": "./node_modules/@dotlab-hq/llm-proxy/schema.json"
```

### 模型配置

每个后端配置包括:

```jsonc
{
  // Unique identifier for this backend
  "id": "primary-openai",
  // Display name
  "name": "Primary Instance",
  // Models this backend supports
  "models": ["gpt-3.5-turbo", "gpt-4"],
  // Track rate limits per instance
  "individualLimit": true,
  // API endpoint (OpenAI-compatible)
  "baseUrl": "https://api.openai.com/v1",
  // API authentication key
  "apiKey": "sk-your-api-key-here",
  // Rate limiting per backend
  "rateLimit": {
    "tokensPerMinute": 90000,
    "requestsPerMinute": 3500,
    "requestsPerDay": 200000
  }
}
```

## API 终点

### 获取缓存状态

```bash
curl http://localhost:25789/
```

### 获取统计

```bash
curl http://localhost:25789/stats
```

自动装入服务器启动时使用当前速率限制 .

### OpenAI 兼容端点

-   `POST /v1/chat/completions` - 聊天结束
-   `POST /v1/completions` - 文本完成情况
-   `POST /v1/embeddings` - 内嵌物
-   `GET /v1/models` - 列出现有模式

示例

```bash
curl -X POST http://localhost:25789/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer llm-proxy" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

## 发展

### 在开发模式中运行

```bash
bun run dev
```

### 类型检查

```bash
bun run types
```

### 运行测试

```bash
bun run testify
```

### 本地链接软件包

```bash
bun link
```

用于其他项目的当地登记:

```bash
bun link @dotlab-hq/llm-proxy
```

### 建立用于分发的 CLI

```bash
bun run build
```

创建 `dist/cli.js` (独立CLI可执行).

## 特征

✅ **OpenAI 兼容** - 更换OpenAI API  
✅ **多个后端** - 多个供应商的负载平衡  
✅ **限制费率** - 外观符号/请求限制  
✅ **缓存** - 内存或后置状态  
✅ **自动挂起** - 服务器启动时加载的统计数据  
✅ **模块化 CLI** - 分开的命令和公用事业  
✅ **动态模板** - 总是使用来自GitHub的最新计划  
✅ **JSONC 配置** - 提供更好的文件的评论  
✅ **Bun 已链接** - 地方一揽子发展支助  
✅ **类型脚本** - 全类型安全

## 处理错误

所有错误都以 OpenAI 兼容格式返回 :

-   **400个** - 无效请求(丢失模型,无效参数)
-   **429个** - 超过费率限额(下个后端)
-   **502 (中文(简体) )** - 所有后端都失败了
-   **第503条** - 没有配置后端

堆栈痕迹被压制,只显示方便用户的信息.

## CLI 架构

关于CLI结构和发展的详情,请参看: [(智利语).md](https://npmcn.com/package/%40dotlab-hq/llm-proxy/docs/CLI_ARCHITECTURE.md)。 。 。 .

## 生产部署

### 1\. 建立国家能力倡议

```bash
bun run build
```

### 2\. 用于项目

```bash
npx @dotlab-hq/llm-proxy init
npx @dotlab-hq/llm-proxy serve
```

### 环境变量

使用 `${VAR_NAME}` 在你身边 `model.jsonc` 参考环境变量:

```jsonc
{
  "models": {
    "openai": [
      {
        "apiKey": "${OPENAI_API_KEY}",
        "baseUrl": "https://api.openai.com/v1",
        "models": ["gpt-3.5-turbo"]
      }
    ]
  }
}
```

## 建筑

-   **浩诺** - 快速而轻巧的HTTP服务器
-   **佐德语Name** - 类型安全配置验证
-   **@ clack/ 瞬间** - 美丽的互动性CLI
-   **阿宝** - 快速JavaScript运行时间
-   **多后端** - 供应商之间的负载平衡
-   **限制费率** - Granular用途跟踪
-   **缓存** - 可插接适配器(记忆/雷地斯)

## 许可证

麻省理工学院

* * *

由 Dotlab 总部创建

## 常见问题

### @dotlab-hq/llm-proxy 是什么？

LLM 语言 具有 OpenAI 兼容性的代理服务器

### 如何安装 @dotlab-hq/llm-proxy？

在项目目录运行 npm install @dotlab-hq/llm-proxy，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：typescript（^5）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 llm-proxy，可以用 npx llm-proxy 直接运行。

### @dotlab-hq/llm-proxy 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @dotlab-hq/llm-proxy 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @dotlab-hq/llm-proxy 可以商用吗？

@dotlab-hq/llm-proxy 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @dotlab-hq/llm-proxy 的下载量有多少？

根据 npm 官方下载统计，@dotlab-hq/llm-proxy 在 2026/10/13 – 2026/11/11 这 30 天内被下载 5,182 次，日均约 173 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dotlab-hq/llm-proxy 还在维护吗？

最新版本 1\.0\.12 发布于 2026/05/04（6 个月前）；至今共发布 13 个版本，其中过去 12 个月发布了 13 个；首次发布于 2026/05/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。