API 密钥#

Ultralytics Platform API 密钥可为远程训练、推理和自动化提供安全的编程访问。你可以创建带名称的密钥，并通过 AES-256-GCM 加密满足不同用途的需求。

创建 API 密钥#

创建新的 API 密钥：

1. 前往 Settings > API Keys
2. 点击 Add Key，然后选择 Ultralytics 作为提供商
3. 为密钥输入名称（例如“训练服务器”）
4. 点击 Create Key

密钥名称#

为密钥起一个能说明用途的名称：

• 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"）。如果省略 api_key，SDK 会读取 ULTRALYTICS_API_KEY 或由 yolo login 保存的密钥：

from ultralytics_platform import Platform

client = Platform(api_key="YOUR_API_KEY")

如需查看所有可用端点，请参阅 REST API 参考。

远程训练#

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

开始之前，请在 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

如需完整的远程训练指南，请参阅 云端训练。

管理密钥#

查看密钥#

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

每行密钥会显示密钥名称、密钥前缀、创建日期、用于复制完整密钥的按钮，以及移除（垃圾桶）按钮。

撤销密钥#

如果密钥已泄露或不再需要，请撤销：

1. 在 API 密钥部分找到该密钥
2. 点击移除（垃圾桶）按钮
3. 点击 Remove Key 进行确认

重新生成密钥#

如果密钥已泄露：

1. 创建一个同名的新密钥
2. 更新你的应用
3. 撤销旧密钥

工作区 API 密钥#

API 密钥的作用范围仅限于当前活动工作区：

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

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

本地部署工作器密钥#

连接本地部署主机会生成一个单独的工作器密钥。工作器密钥通过本地部署集成进行管理，而不在此选项卡中管理；它们不会与 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. 降低请求频率——按类别划分的限制请参阅速率限制表
2. 使用 Retry-After 标头实现指数退避
3. 如果你需要独立的推理容量，请使用专用端点

常见问题#