docs/huggingface-spaces.md

Hugging Face Spaces 部署

本專案可以用 Docker Space 部署。Space 只會對外暴露一個 HTTP port，因此主 API 在 Hugging Face 上固定使用 7860，流式代理仍可在容器內部使用 STREAM_PORT。

1. 先準備 Google AI Studio 認證

Hugging Face 的容器是 headless，不能在啟動時互動登入。請先在本機完成一次登入並產生 auth_profiles/active/*.json：

poetry install
poetry run python launch_camoufox.py --debug

確認 auth_profiles/active/ 下面有可用的 .json 後，把它轉成 base64，準備放到 Hugging Face Secret。

PowerShell:

[Convert]::ToBase64String([IO.File]::ReadAllBytes("auth_profiles\active\your-auth.json"))

Bash:

base64 -w 0 auth_profiles/active/your-auth.json

2. 建立 Space

在 Hugging Face 建立新的 Space：

• SDK: Docker
• Visibility: 建議 Private
• Hardware: 建議至少 4GB RAM；瀏覽器啟動失敗時請升級硬體

3. 設定 Secrets

在 Space 的 Settings -> Secrets 新增：

Secret	必填	說明
AISTUDIO_AUTH_JSON_B64	是	上一步產生的 base64 auth JSON
AISTUDIO_PROXY_API_KEYS	強烈建議	API key，多組可用換行、逗號或分號分隔
UNIFIED_PROXY_CONFIG	視網路需要	例如 http://host:port 或 socks5://host:port
SERVER_LOG_LEVEL	否	預設 INFO
STREAM_PORT	否	預設 3120；設 0 可關閉內部流式代理

也可以改用 AISTUDIO_AUTH_JSON 放原始 JSON，但 base64 對多行內容較穩。

4. 推送到 Space

如果你用這個 repo 直接部署：

git remote add space https://huggingface.co/spaces/<user>/<space-name>
git push space main

若 Hugging Face Space 是空 repo，也可以把本專案內容推到該 Space repo。根目錄的 Dockerfile 和 README metadata 會讓 Space 自動用 Docker 建置。

5. 使用 API

部署完成後：

curl https://<user>-<space-name>.hf.space/health
curl https://<user>-<space-name>.hf.space/v1/models

OpenAI compatible base URL:

https://<user>-<space-name>.hf.space/v1

如果設定了 AISTUDIO_PROXY_API_KEYS，請用：

Authorization: Bearer <your-key>

注意

• 不要把 auth_profiles/*.json commit 到 Git 或公開 Space。
• Free Space 會休眠，重啟後會重新載入 Secret 中的 auth JSON。
• Google 登入狀態可能過期，過期時需要在本機重新登入並更新 AISTUDIO_AUTH_JSON_B64。