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

```bash
poetry install
poetry run python launch_camoufox.py --debug
```

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

PowerShell:

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

Bash:

```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 直接部署：

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

部署完成後：

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

OpenAI compatible base URL:

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

如果設定了 `AISTUDIO_PROXY_API_KEYS`，請用：

```text
Authorization: Bearer <your-key>
```

## 注意

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