跳转至内容

API 密钥

Ultralytics 远程训练、推理和自动化操作的安全程序化访问。可创建采用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该平台会解密并显示您的密钥，以便您随时复制。

密钥是区域特定的吗？

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

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

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



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

评论