---
title: PDFMathTranslate Next
emoji: 📄
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
---

## PDFMathTranslate-next on HuggingFace Spaces

这个仓库部署一个单体 FastAPI 服务，包含：

1. 用户登录（Session Cookie）
2. 中文 Web UI（上传 PDF、查看任务、下载结果）
3. 任务队列（单 worker）调用 `pdf2zh_next` Python API
4. 内部 OpenAI 兼容代理：`/internal/openai/v1/chat/completions`（按模型路由）
5. 按登录用户名计费（token + USD）

### 运行架构

1. 用户访问 `:7860` 登录并提交翻译任务
2. 后台 worker 调用 `pdf2zh_next`，并把 `chat/completions` 请求发到本机内部代理
3. 内部代理根据 `model` 路由上游：
   - `SiliconFlowFree` -> 作者维护的 `chatproxy` 接口
   - 其他模型 -> OpenAI 风格上游（默认 OpenAI 官方）
4. 计费按 `username` 聚合，前端展示账单

### 必需 Secret

在 HuggingFace Space 设置：

- `BASIC_AUTH_USERS`（多行文本）

`BASIC_AUTH_USERS` 格式：

```text
alice:your_password_1
bob:your_password_2
```

规则：

- 每行一个账号，格式 `username:password`
- 空行和 `#` 开头行会被忽略
- 支持明文密码与 bcrypt 哈希

### 可选环境变量

- `SESSION_SECRET`：Session 签名密钥
- `INTERNAL_KEY_SALT`：内部 key 生成盐（默认复用 `SESSION_SECRET`）
- `DEFAULT_LANG_IN`：默认源语言（默认 `en`）
- `DEFAULT_LANG_OUT`：默认目标语言（默认 `zh`）
- `TRANSLATION_QPS`：翻译 QPS（默认 `4`）
- `DATA_DIR`：数据目录（默认 `/data`）
- `OPENAI_API_KEY`：仅当你希望代理“非 SiliconFlowFree 模型”时需要
- `OPENAI_UPSTREAM_CHAT_URL`：非 SiliconFlowFree 模型的 OpenAI 风格上游地址

### 固定模型与路由表

- 前端不提供模型选择，任务模型固定为 `SiliconFlowFree`
- 路由表在 `src/gateway.py` 的 `MODEL_ROUTE_TABLE`
- 当前只维护一条：`SiliconFlowFree`，带两个 `chatproxy` 备用地址

### 健康检查

`/healthz` 无需认证，返回 `200 ok`。

### 本地构建示例

```bash
docker build -t pdf2zh-gated .
docker run --rm -p 7860:7860 \
  -e BASIC_AUTH_USERS=$'alice:pass1\nbob:pass2' \
  pdf2zh-gated
```

### CI 同步到 Spaces 的排除策略

- 本仓库可本地维护密码文件：`basic_auth_users.txt`
- CNB `push` 分两个阶段：
  - 阶段 1：读取 `basic_auth_users.txt`，自动更新 Space Secret `BASIC_AUTH_USERS`
  - 阶段 2：删除排除文件后，强制推送代码到 HuggingFace Spaces
- 推送前会删除以下文件：
  - `.cnb.yml`
  - `basic_auth_users.txt`
  - `src/scripts/`
- 排除列表在 `.cnb.yml` 的 `HF_EXCLUDE_FILES` 中配置（空格分隔）
- 密钥更新脚本：`src/scripts/update_space_secret.py`