215 lines
5.4 KiB
Markdown
215 lines
5.4 KiB
Markdown
# Lingma OpenAI Gateway
|
||
|
||
把本地 Lingma 能力封装为 OpenAI 兼容接口，支持：
|
||
|
||
- `GET /v1/models`
|
||
- `POST /v1/chat/completions`
|
||
- `stream=true`（SSE）
|
||
- Bearer API Key 鉴权
|
||
|
||
## 1. 准备目录
|
||
|
||
```bash
|
||
mkdir -p data
|
||
```
|
||
|
||
说明：
|
||
|
||
- 启动时会自动获取最新插件并提取 `Lingma` 到 `data/bin`。
|
||
- 默认通过 VSCode Marketplace 查询最新版本，再下载对应 VSIX。
|
||
- 登录态与运行数据统一写入 `data/.lingma`。
|
||
|
||
## 2. 配置环境变量
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
至少修改：
|
||
|
||
- `API_KEYS`
|
||
- `LINGMA_USERNAME`
|
||
- `LINGMA_PASSWORD`
|
||
|
||
如果你的 Lingma 路径不同，修改：
|
||
|
||
- `LINGMA_BIN`
|
||
|
||
可选（企业专属域）：
|
||
|
||
- `DEDICATED_DOMAIN_URL`
|
||
|
||
### `.env` 字段说明（简版）
|
||
|
||
- `HOST`：网关监听地址（通常 `0.0.0.0`）
|
||
- `PORT`：网关监听端口（外部调用端口）
|
||
- `API_KEYS`：Bearer Key，多个用逗号分隔
|
||
- `LINGMA_BIN`：容器内 Lingma 路径
|
||
- `LINGMA_SOURCE_TYPE`：二进制来源（`marketplace`/`vsix`）
|
||
- `LINGMA_MARKETPLACE_PUBLISHER`：Marketplace 发布者
|
||
- `LINGMA_MARKETPLACE_EXTENSION`：Marketplace 扩展名
|
||
- `LINGMA_VSIX_URL`：VSIX 下载地址（最新优先）
|
||
- `PIP_REGION`：构建 pip 源策略（`auto`/`CN`/`GLOBAL`）
|
||
- `LINGMA_BOOTSTRAP_ALWAYS`：启动时是否总尝试刷新 Lingma
|
||
- `LINGMA_FORCE_REFRESH`：是否强制刷新（忽略本地缓存）
|
||
- `LINGMA_WORK_DIR`：Lingma 工作目录（登录与会话数据）
|
||
- `LINGMA_SOCKET_PORT`：Lingma 本地 WS 端口
|
||
- `LINGMA_STARTUP_TIMEOUT`：Lingma 启动等待秒数
|
||
- `LINGMA_RPC_TIMEOUT`：单次 RPC 超时秒数
|
||
- `DEFAULT_MODEL`：默认模型（无法映射时兜底）
|
||
- `DEFAULT_ASK_MODE`：默认模式（`chat`/`agent`）
|
||
- `DEDICATED_DOMAIN_URL`：企业专属域（可留空）
|
||
- `AUTO_LOGIN_ENABLED`：未登录时自动登录开关
|
||
- `AUTO_LOGIN_HEADLESS`：自动登录是否无头浏览器
|
||
- `AUTO_LOGIN_TIMEOUT`：自动登录超时秒数
|
||
- `AUTO_LOGIN_MAX_RETRY`：自动登录重试次数
|
||
- `LINGMA_USERNAME`：Lingma 登录用户名
|
||
- `LINGMA_PASSWORD`：Lingma 登录密码
|
||
|
||
### `.env` 最小必填示例
|
||
|
||
```env
|
||
PORT=8317
|
||
API_KEYS=sk-your-api-key
|
||
LINGMA_USERNAME=your-username
|
||
LINGMA_PASSWORD=your-password
|
||
LINGMA_BIN=/app/data/bin/Lingma
|
||
LINGMA_WORK_DIR=/app/data/.lingma/vscode/sharedClientCache
|
||
LINGMA_SOURCE_TYPE=marketplace
|
||
LINGMA_MARKETPLACE_PUBLISHER=Alibaba-Cloud
|
||
LINGMA_MARKETPLACE_EXTENSION=tongyi-lingma
|
||
LINGMA_VSIX_URL=https://tongyi-code.oss-cn-hangzhou.aliyuncs.com/vscode/tongyi-lingma-latest.vsix
|
||
PIP_REGION=auto
|
||
DEDICATED_DOMAIN_URL=
|
||
```
|
||
|
||
### 数据目录说明
|
||
|
||
- 本项目所有持久化数据都在 `./data`：
|
||
- `data/bin/Lingma`：自动提取的 Lingma 二进制
|
||
- `data/.lingma/...`：Lingma 登录态、缓存、日志
|
||
|
||
## 3. Docker 运行
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
```
|
||
|
||
说明：
|
||
|
||
- 构建阶段已默认使用腾讯云 PyPI 镜像（`mirrors.cloud.tencent.com`）。
|
||
- 如需自定义镜像源，可在 `docker-compose.yml` 的 `build.args` 中修改。
|
||
|
||
查看日志：
|
||
|
||
```bash
|
||
docker compose logs -f
|
||
```
|
||
|
||
## 4. 调用示例
|
||
|
||
### 模型列表
|
||
|
||
```bash
|
||
curl -s http://127.0.0.1:8317/v1/models \
|
||
-H "Authorization: Bearer sk-your-api-key"
|
||
```
|
||
|
||
说明：
|
||
|
||
- `id` 保持 Lingma 原始模型 key（兼容 OpenAI 客户端）
|
||
- `name` 提供可读名称（如 `qwen3.6-plus`）
|
||
- 调用 `/v1/chat/completions` 时，`model` 既可传 `id`，也可直接传 `name`
|
||
|
||
### 非流式聊天
|
||
|
||
```bash
|
||
curl -s http://127.0.0.1:8317/v1/chat/completions \
|
||
-H "Authorization: Bearer sk-your-api-key" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"model": "dashscope_qmodel",
|
||
"messages": [
|
||
{"role": "user", "content": "写一个 python hello world"}
|
||
]
|
||
}'
|
||
```
|
||
|
||
### 流式聊天
|
||
|
||
```bash
|
||
curl -N http://127.0.0.1:8317/v1/chat/completions \
|
||
-H "Authorization: Bearer sk-your-api-key" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"model": "dashscope_qmodel",
|
||
"stream": true,
|
||
"messages": [
|
||
{"role": "user", "content": "介绍一下你自己"}
|
||
]
|
||
}'
|
||
```
|
||
|
||
## 5. 统计与监控
|
||
|
||
支持调用次数与 token（估算值）统计：
|
||
|
||
- `GET /internal/stats`（需 Bearer）
|
||
- `GET /metrics`（Prometheus 文本格式）
|
||
|
||
示例：
|
||
|
||
```bash
|
||
curl -s http://127.0.0.1:8317/internal/stats \
|
||
-H "Authorization: Bearer sk-xxx"
|
||
```
|
||
|
||
```bash
|
||
curl -s http://127.0.0.1:8317/metrics
|
||
```
|
||
|
||
说明：
|
||
|
||
- `usage.prompt_tokens/completion_tokens` 为估算值（按字节近似换算）。
|
||
- 非流式响应里会附带 `usage` 字段。
|
||
|
||
## 6. 容器内自动登录
|
||
|
||
已内置自动登录能力（Playwright + Chromium）。
|
||
|
||
你可以主动触发：
|
||
|
||
```bash
|
||
curl -s -X POST http://127.0.0.1:8317/internal/auto-login/start \
|
||
-H "Authorization: Bearer sk-your-api-key"
|
||
```
|
||
|
||
查看状态：
|
||
|
||
```bash
|
||
curl -s http://127.0.0.1:8317/internal/auto-login/status \
|
||
-H "Authorization: Bearer sk-your-api-key"
|
||
```
|
||
|
||
说明：
|
||
|
||
- 若未登录，`/v1/models` 与 `/v1/chat/completions` 也会尝试自动登录。
|
||
- 账号密码来自 `.env`（`LINGMA_USERNAME` / `LINGMA_PASSWORD`）。
|
||
- 建议仅在受控环境使用，并妥善保护 `.env`。
|
||
|
||
## 7. agent 模式
|
||
|
||
在 v1 中，若 `model` 传 `agent` 或 `lingma-agent`，会走 agent 模式。
|
||
|
||
```bash
|
||
curl -s http://127.0.0.1:8317/v1/chat/completions \
|
||
-H "Authorization: Bearer sk-xxx" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"model": "agent",
|
||
"messages": [
|
||
{"role": "user", "content": "分析这个项目目录结构"}
|
||
]
|
||
}'
|
||
```
|