| --- |
| 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` |
|
|
