API 密钥#

Ultralytics Platform API 密钥支持对远程训练、推理和自动化进行安全的程序化访问。你可以使用 AES-256-GCM 加密为不同使用场景创建命名密钥。

创建 API 密钥#

创建新的 API 密钥：

1. 前往 设置 > API 密钥
2. 点击 Add Key 并选择 Ultralytics 作为提供商
3. 输入密钥名称（例如“训练服务器”）
4. 点击 创建密钥

密钥名称#

为你的密钥提供描述性名称：

• training-server - 用于远程训练机器
• ci-pipeline - 用于 CI/CD 集成
• local-dev - 用于本地开发

密钥显示#

创建后，密钥会显示在确认对话框中：

用于代理的提供商密钥#

同一个 Settings > API Keys 选项卡还存储了代理使用的外部模型提供商的密钥。只有工作空间所有者可以添加、替换或移除这些密钥；团队成员可以查看哪些提供商已连接。请让所有者连接缺失的提供商。作为所有者连接提供商的方法如下：

1. 点击 Add Key。
2. 选择与你的工作流语言或视觉语言模型相匹配的提供商。
3. 将该提供商的 API 密钥粘贴到 API Key 中，然后点击 Save Key。对话框中的 Get an API key 链接会打开提供商的密钥页面。

Ultralytics 密钥不会对外部模型提供商进行身份验证。提供商的使用费用通过与保存的密钥关联的提供商账户进行计费。使用密钥行的编辑控件来替换提供商密钥。

密钥格式#

API 密钥遵循以下格式：

ul_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4

• 前缀：ul_ 用于标识 Ultralytics 密钥
• 主体：40 个随机十六进制字符
• 总长度：43 个字符

密钥安全性#

• 密钥使用 AES-256-GCM 加密存储，绝不以明文形式存储
• 前 11 个字符（ul_ 加 8 个十六进制字符）作为显示前缀，因此无需暴露完整密钥即可识别密钥

使用 API 密钥#

环境变量#

将密钥设置为环境变量：

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

YOLO CLI#

使用 Python>=3.11 上的 YOLO CLI 验证并保存密钥：

yolo login YOUR_API_KEY

使用 yolo logout 删除已保存的密钥。

HTTP 标头#

在 API 请求中包含密钥：

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/...

或者将其传递给 Python SDK (pip install "ultralytics-platform>=0.1.45")，该 SDK 会在省略 api_key 时读取 ULTRALYTICS_API_KEY 或通过 yolo login 保存的密钥：

from ultralytics_platform import Platform

client = Platform(api_key="YOUR_API_KEY")

有关所有可用端点，请参阅 REST API Reference。

远程训练#

使用你的密钥启用指标流式传输。

在开始之前，请在 Python>=3.11 上安装或更新 Ultralytics 软件包：

pip install -U ultralytics

export ULTRALYTICS_API_KEY="YOUR_API_KEY"
yolo train model=yolo26n.pt data=coco.yaml project=username/project name=exp1

有关完整的远程训练指南，请参阅 Cloud Training。

管理密钥#

查看密钥#

所有密钥都会列在 Settings > API Keys 选项卡中：

每个密钥卡片都会显示密钥名称、可复制的密钥值、相对创建时间和撤销按钮。

撤销密钥#

撤销已泄露或不再需要的密钥：

1. 在 API 密钥部分找到该密钥
2. 点击 撤销（垃圾桶）按钮
3. 确认撤销

重新生成密钥#

如果密钥已泄露：

1. 使用相同名称创建新密钥
2. 更新你的应用程序
3. 撤销旧密钥

工作区 API 密钥#

API 密钥的作用域限定为当前活动工作区：

• 个人工作区：密钥以你的个人账户身份进行身份验证
• 团队工作区：密钥以团队工作区所有者身份进行身份验证，并在该工作区中拥有完整的所有者权限

在侧边栏中切换工作区时，API 密钥部分会显示该工作区的密钥。由于工作区密钥具有所有者权限，只有工作区所有者可以创建、查看或撤销密钥。有关角色详情，请参阅 Teams。

On Premise Worker 密钥#

连接 On Premise 主机会生成单独的 worker 密钥。Worker 密钥从 On Premise 集成中管理，而不是从此选项卡管理；它们不会与 API 密钥一同列出。断开主机连接即可撤销该密钥，同时也会取消该主机排队中和正在运行的作业。

安全最佳实践#

应该做#

• 将密钥存储在环境变量中
• 为不同环境使用不同的密钥
• 及时撤销未使用的密钥
• 定期轮换密钥
• 使用描述性名称来标识密钥用途

不要做#

• 将密钥提交到版本控制系统
• 在多个应用程序之间共享密钥
• 在应用程序输出中记录密钥
• 将密钥嵌入客户端代码

密钥轮换#

定期轮换密钥以确保安全：

1. 使用相同名称创建新密钥
2. 更新应用程序以使用新密钥
3. 确认应用程序正常运行
4. 撤销旧密钥

故障排除#

无效密钥错误#

Error: Invalid API key

解决方案：

1. 确认密钥已正确复制（包括 ul_ 前缀）
2. 检查密钥是否已被撤销
3. 确认环境变量已设置
4. 确保你使用的是 Python>=3.11 和 ultralytics>=8.4.120

权限被拒绝#

Error: Permission denied for this operation

解决方案：

1. 确认你是资源所有者，或拥有适当的工作区访问权限
2. 检查密钥是否属于正确的工作区
3. 如果你正在团队工作区中管理密钥，请确认你是工作区所有者——其他角色会获得 Workspace owner access required
4. 如有需要，创建新密钥

请求受限#

Error: Rate limit exceeded

解决方案：

1. 降低请求频率——有关按类别划分的限制，请参阅 rate limit table
2. 使用 Retry-After 标头实现指数退避
3. 需要隔离的推理容量时，使用 dedicated endpoint

常见问题#