跳转至内容

API 密钥

Ultralytics Platform API密钥可实现安全的程序化访问，用于远程训练、推理和自动化。创建带有AES-256-GCM加密的命名密钥以适应不同的用例。

Ultralytics 平台设置个人资料选项卡 API 密钥列表

创建 AP 密钥

创建新的 API 密钥：

  1. 前往设置 > 个人资料
  2. 滚动到API 密钥部分
  3. 点击 创建密钥
  4. 输入密钥名称（例如，“训练服务器”）
  5. 点击 创建密钥

Ultralytics 平台设置个人资料选项卡创建 API 密钥对话框

密钥名称

为您的密钥指定一个描述性名称：

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

密钥显示

创建后，密钥将显示一次：

Ultralytics 平台设置资料选项卡：API 密钥创建复制对话框

复制您的密钥

创建后复制您的密钥以便查阅。密钥在密钥列表中也可见——平台会解密并显示完整的密钥值，以便您随时复制。

密钥格式

API 密钥遵循以下格式：

ul_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4
  • 前缀: ul_ 用于识别 Ultralytics 密钥
  • 主体：40 个随机十六进制字符
  • 总计：43 个字符

关键安全

  • 密钥存储采用AES-256-GCM 加密
  • 身份验证使用SHA-256哈希以实现快速前缀查找和哈希比较
  • 完整的密钥值绝不以明文形式存储

使用 API 密钥

环境变量

将您的密钥设置为环境变量：

export ULTRALYTICS_API_KEY="ul_your_key_here"

$env:ULTRALYTICS_API_KEY = "ul_your_key_here"

YOLO CLI

使用 YOLO CLI 设置密钥：

yolo settings api_key="ul_your_key_here"

代码中

在您的python脚本中使用此密钥：

import os

# From environment (recommended)
api_key = os.environ.get("ULTRALYTICS_API_KEY")

# Or directly (not recommended for production)
api_key = "ul_your_key_here"

HTTP 请求头

在API请求中包含此密钥：

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

请参阅 REST API 参考，以了解所有可用端点。

远程训练

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

软件包版本要求

平台集成需要ultralytics>=8.4.14。更低版本将无法与平台配合使用。

pip install "ultralytics>=8.4.14"

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

请参阅 云训练，以获取完整的远程训练指南。

管理密钥

查看密钥

所有密钥都列在 Settings > Profile 在 API 密钥部分下：

每个密钥卡片都显示密钥名称、完整的解密密钥值（可复制）、相对创建时间以及一个撤销按钮。

撤销密钥

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

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

立即生效

撤销立即生效。任何使用此密钥的应用程序将停止工作。

重新生成密钥

如果密钥已泄露：

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

工作区API密钥

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

  • 个人工作区：密钥以您的个人账户进行身份验证
  • 团队工作区：密钥在团队上下文中进行身份验证

当在侧边栏切换工作区时，API 密钥部分会显示该工作区的密钥。管理工作区 API 密钥需要编辑者或更高角色。有关角色详情，请参阅团队。

安全最佳实践

应做

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

不应做

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

密钥轮换

为安全起见，定期轮换密钥：

  1. 创建同名新密钥
  2. 更新应用程序以使用新密钥
  3. 验证应用程序是否正常工作
  4. 撤销旧密钥

轮换计划

对于敏感应用程序，请考虑每90天轮换一次密钥。

故障排除

无效密钥错误

Error: Invalid API key

解决方案：

  1. 验证密钥是否正确复制（包括 ul_ 前缀)
  2. 检查密钥是否未被撤销
  3. 确认环境变量已设置
  4. 确保您正在使用 ultralytics>=8.4.14

权限拒绝

Error: Permission denied for this operation

解决方案：

  1. 验证您是资源所有者或拥有适当的工作区访问权限
  2. 检查密钥是否属于正确的工作区
  3. 如果需要，创建新密钥

速率限制

Error: Rate limit exceeded

解决方案：

  1. 降低请求频率 — 有关每个端点的限制，请参阅速率限制表。
  2. 使用指数退避机制 Retry-After 标头
  3. 使用专用端点实现无限推理吞吐量

常见问题

我可以创建多少个密钥？

API 密钥没有硬性限制。您可以根据不同的应用程序和环境需求创建任意数量的密钥。

密钥会过期吗？

密钥不会自动过期。它们在被撤销之前始终有效。为安全起见，请考虑实施轮换机制。

创建后我能看到我的密钥吗？

是的，完整的密钥值可在以下密钥列表中查看 Settings > Profile. 平台会解密并显示您的密钥，以便您随时复制。

密钥是区域特定的吗？

密钥可在不同区域使用，但只能访问您账户所在区域的数据。

我可以与团队成员共享密钥吗？

最佳实践：让每个团队成员创建自己的密钥。对于团队工作区，具有编辑者角色或更高权限的每个成员都可以创建限定于该工作区的密钥。



📅 创建于 2 个月前 ✏️ 更新于 5 天前
glenn-jochermykolaxboikosergiuwaxmannLaughing-q

评论