README.md

metadata

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 格式：

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。

本地构建示例

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