跳到主要内容

身份验证和授权

要调用本规范中提到的任何 API，客户端必须首先获取令牌（和 URL）以对提供这些 API 的服务器进行身份验证。

Xet 协议服务器使用由 Hugging Face Hub（<https://huggingface.co\>）生成的令牌进行 Bearer 身份验证。

以下部分说明如何获取此类令牌。

令牌请求 API 端点​

URL 模式：

https://huggingface.co/api/{repo_type}s/{repo_id}/xet-{token_type}-token/{revision}

参数：

所有参数都是形成 URL 所必需的。

  • repo_type：仓库类型 - model、dataset 或 space
  • repo_id：仓库标识符，格式为 namespace/repo-name
  • token_type：read 或 write。
  • revision：Git 修订版本（分支、标签或提交哈希；如果不需要特定 ref，默认使用 main）

要了解 token_type 值之间的区别，请继续阅读本文档中的令牌作用域。

示例 URL：

https://huggingface.co/api/models/sentence-transformers/all-MiniLM-L6-v2/xet-read-token/main
https://huggingface.co/api/datasets/HuggingFaceM4/the_cauldron/xet-write-token/v1.1
https://huggingface.co/api/spaces/jsulz/ready-xet-go/xet-read-token/main

HTTP 方法： GET

必需标头：

  • Authorization：用于 Hugging Face Hub 身份验证的 Bearer 令牌

响应格式​

具有以下格式的 JSON 编码对象：

{
   "accessToken": string,
   "exp": number,
   "casUrl": string,
}
  • accessToken 是在 Xet CAS 服务上调用 API 时使用的令牌（本规范中表示的任何 Xet API）
  • exp 是此令牌过期的 unix 时间戳
  • casUrl 是 API 服务端点 URL

用户可以假设 "accessToken" 和 "casUrl" 字段长度上限为 64000 个字符。

示例响应对象​

{
   "accessToken": "xet_xxxxxxxxxxx",
   "exp": 1848535668,
   "casUrl": "https://cas-server.xethub.hf.co"
}

错误处理​

HTTP 错误​

  • 401 Unauthorized：无效或缺少 Hub 身份验证令牌
  • 403 Forbidden：请求的令牌类型权限不足
  • 404 Not Found：仓库或修订版本不存在

实现示例​

以下是基本实现流程：

  1. 发出请求：

    GET /api/models/black-forest-labs/FLUX.1-dev/xet-read-token/main
    Host: huggingface.co
    Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

  2. 解析响应

    endpoint = response_json["casUrl"]
    access_token = response_json["accessToken"]
    expiration = response_json["exp"]

  3. 使用令牌与 Xet 服务： 使用 accessToken 键的值进行 Bearer 身份验证，在 endpoint 处与 Xet 服务进行身份验证，直到 expiration 时间。

  4. 令牌刷新（需要时）： 使用相同的 API 生成新令牌。

备注

在 xet-core 中，我们应该在提供的 expiration 时间之前添加 30 秒的缓冲时间来刷新令牌。

令牌作用域​

Xet 令牌可以具有 read 或 write 作用域。 write 作用域取代 read 作用域，使用 write 作用域令牌时可以调用所有 read 作用域 API。 发出的令牌类型由从 Hugging Face Hub 请求令牌时的 token_type URI 路径组件确定（见上文）。

检查 API 规范以了解调用每个 API 所需的作用域级别（简要地说，只有 POST /shard 和 POST /xorb/* API 需要 write 作用域）。

Xet 令牌的作用域仅限于为其颁发的仓库和 ref。要从不同的仓库或 ref（不同的分支）上传或下载，客户端必须被颁发不同的令牌。

相对于 Hugging Face Hub 身份验证令牌的令牌作用域​

从 Hugging Face Hub 请求 Xet 令牌时，只有当你实际有权访问它们时（基于你的 Hub 身份验证令牌提供的访问权限），你才会收到与请求参数匹配的 Xet 令牌。

如果你需要 write 作用域 Xet 令牌，则必须使用对你要访问的特定仓库和 ref 具有写入访问权限的 Hugging Face Hub 令牌来请求它。

如果你请求 read 作用域 Xet 令牌，则必须使用对你想要访问的特定仓库和 ref 至少具有读取访问权限的 Hugging Face Hub 令牌来请求它。

如果你使用细粒度 Hugging Face Hub 访问令牌，你的令牌必须分别对仓库内容具有读取或写入访问权限，才能被颁发读取或写入 Xet 令牌。

安全注意事项​

  • Xet 令牌是时间限制的，应在过期之前刷新/交换
  • 安全存储令牌，不应记录它们（包括 Hub 身份验证令牌和 Xet 令牌）
  • 应尽可能使用读取令牌；仅在必要时请求写入令牌

序列图​

最后于 更新