> ## Documentation Index
> Fetch the complete documentation index at: https://starforge.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# HuggingFace 集成

> 账号关联、gated 资源预检、export 推 Hub

启用 HF 集成后（服务端 `FORGE_HF_OAUTH_*` 配置），平台以**用户级** HF 身份工作——不再共享一个团队 token。

## 能做什么

| 能力               | 说明                                                         |
| ---------------- | ---------------------------------------------------------- |
| **账号关联**         | 控制台 **HuggingFace** 页 OAuth 关联个人 HF 账号                     |
| **提交预检**         | 提交时校验模型 / 数据集权限：gated repo（如 Llama 系）未授权提前报错，而不是训练跑一半失败    |
| **Export 推 Hub** | `sf export --push-repo user/name` 时服务端注入**当前用户**的 HF token |

## 关联账号

<Steps>
  <Step title="打开 HuggingFace 页">
    控制台侧栏 → **HuggingFace**（`/integrations/hf`）。未启用集成时该入口不显示。
  </Step>

  <Step title="OAuth 授权">
    默认只读 scope（`read-repos`、`gated-repos`）。平台开启写权限（`FORGE_HF_OAUTH_WRITE_ENABLED=true`）后需重新授权获得 push scope。
  </Step>
</Steps>

## CLI 侧

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
sf export my-exp \
  --checkpoint <ckpt> --checkpoint-format nemo-dcp \
  --push-repo myorg/my-model
```

<Note>
  `--push-repo` 的 repo 名经过严格校验（`org/name` 形态，防选项注入）；推送失败不影响本地导出产物。
</Note>