Ultralytics YOLO27：
Get Started

专用端点#

Ultralytics Platform 可将 YOLO 模型部署到全球 42 个地区的专用端点。每个端点都是单租户服务，拥有唯一的端点 URL 和独立的监控功能。默认资源规格在空闲时会缩减至零；自定义规格则会保持一个预热实例，并按运行时长计费。

Ultralytics Platform 模型部署选项卡（含区域地图和表格）

创建端点#

在部署选项卡中#

在模型的 Deploy 选项卡中部署模型：

  1. 转到你的模型
  2. 点击 部署 选项卡
  3. 查看世界地图和区域表格；表格按从你所在位置测得的延迟排序
  4. 在要使用的区域所在行中点击 部署
  5. 在对话框中查看 CPU、内存、价格和部署名称，然后点击 创建部署

建议名称由模型名称和区域所在城市组成（例如 yolo26n-iowa），部署前可以编辑。如果模型没有权重，该选项卡会显示空状态，而不是区域表格。

在部署选项卡中#

在个人资料页的 部署 选项卡中，或通过侧边栏创建部署：

  1. 在部署选项卡中点击 新建部署，或点击侧边栏中 部署 旁边的 +
  2. 从模型选择器中选择模型；其中会列出已完成的模型
  3. 从小地图或延迟表格中选择区域
  4. 选择 CPU 和内存，查看价格，并按需修改建议的部署名称
  5. 点击 创建部署

Ultralytics Platform 新建部署对话框（含模型选择器和区域地图）

部署生命周期#

连接 Slack 提醒，以便在部署就绪或启动失败时收到消息。

区域选择#

你可以从全球 42 个区域中进行选择。交互式区域地图和表格会显示：

  • 区域标记：按延迟使用从绿色到红色的渐变色标记（延迟较低的区域更偏绿，延迟较高的区域更偏红）
  • 已部署区域：在表格中以“已部署”徽标突出显示
  • 正在部署的区域：地图标记和表格行上会显示动画脉冲指示器
  • 双向高亮：将鼠标悬停在地图上会高亮对应的表格行，反之亦然

Ultralytics Platform 部署选项卡的区域延迟表格（按延迟排序）

模型 Deploy 选项卡中的区域表格包含：

列说明
位置城市和国家/地区，以及国旗图标
区域区域标识符
延迟从你的浏览器测得的 ping 时间
距离与你的大致位置之间的距离，单位为 km
操作部署按钮或“已部署”状态徽标

表格可按城市、国家/地区和区域搜索，默认按延迟排序。

新建部署对话框

New Deployment 对话框（可从部署选项卡或侧边栏打开）会显示一个更简洁的区域表格，其中只有位置、延迟和选择列，并列出速度最快的 20 个区域，同时注明其余区域。使用小地图选择其他任意区域。

延迟的测量方式

你的浏览器会测量到 42 个区域的延迟，结果会缓存 30 分钟，并在 Deploy 选项卡和 New Deployment 对话框之间共享。要从当前网络重新测量，请在模型 Deploy 选项卡中使用 重新扫描 按钮。距离根据请求的大致位置计算，因此只能作为粗略参考，并非精确值。

可用区域#

区域位置
us-central1美国爱荷华州
us-east1美国南卡罗来纳州
us-east4美国弗吉尼亚州北部
us-east5美国俄亥俄州哥伦布市
us-south1美国德克萨斯州达拉斯市
us-west1美国俄勒冈州
us-west2美国加利福尼亚州洛杉矶市
us-west3美国犹他州盐湖城
us-west4美国内华达州拉斯维加斯市
northamerica-northeast1加拿大蒙特利尔
northamerica-northeast2加拿大多伦多
northamerica-south1墨西哥克雷塔罗
southamerica-east1巴西圣保罗
southamerica-west1智利圣地亚哥

端点配置#

新建部署对话框#

New Deployment 对话框可让你选择模型、区域、资源和部署名称：

字段说明
模型使用选择器选择工作区中任意已完成的模型
区域部署区域，可在小地图或延迟表中选择
CPU 和内存选择资源规格并查看显示的价格
部署名称设置模型和区域后自动生成，也可以编辑

Ultralytics Platform 新建部署对话框固定资源默认值

在资源控件中选择 CPU 和内存规格，并在创建部署前查看显示的价格。CPU 选项为 1、2、4、6 或 8 vCPU，内存选项为 2 到 32 GiB；较大的内存规格需要更多 vCPU（例如，16 GiB 至少需要 4 vCPU），对话框会说明任何无效的组合。默认规格（1 vCPU、2 GiB）免费，空闲时会缩减到零。自定义规格会保持一个实例处于预热状态，并从就绪时起按显示的区域小时费率计费，直到你停止端点为止，空闲时间也计费。创建、启动或调整为自定义规格需要有可用额度；工作区额度用尽时，自定义规格端点会自动停止。选择新建部署…时，Agents 会重复使用此对话框。

Ultralytics Platform 新建部署对话框自定义 CPU 内存价格

自动生成的名称

部署名称由模型名称和区域所在城市组成，例如 yolo26n-iowa。名称在同一工作区内必须唯一：如果名称已被占用，对话框会显示行内错误，并禁用创建部署，直到你选择其他名称。

部署选项卡（快速部署）#

从模型的 Deploy 选项卡部署时，会打开同一个对话框，并预先选定模型和区域。创建端点前，请检查资源规格、价格和自动生成的名称。部署创建期间会显示在区域表下方的模型部署列表中。

管理端点#

视图模式#

部署列表支持三种视图模式：

模式说明
卡片卡片显示状态、规格、指标、距离和部署日期
紧凑包含关键指标的小型卡片网格
表格支持排序列的数据表

Ultralytics Platform 部署选项卡活动部署卡片视图

紧凑视图和表格视图

紧凑卡片显示旗帜、名称、城市、状态和三个指标。表格视图可按名称、区域、状态、CPU、内存、HTTP 请求、HTTP 错误率、HTTP P95 延迟、距离和部署时间排序。每张卡片和每一行都链接到部署页面；生命周期操作位于该页面上，侧边栏中部署旁边的垃圾桶图标可将其删除。

部署页面#

每个部署都有自己的页面，位于 /{username}/deploy/{deployment}，页面显示：

  • 页眉：区域旗帜、显示名称（点击即可重命名；页面 URL 和 API 路径会变为新名称对应的 slug，但端点 URL 不变）、状态徽章、位置以及 CPU 和内存规格
  • 操作：状态为就绪时显示更新配置、替换模型和停止部署；状态为已停止时显示启动部署；还有包含信息、刷新和删除部署的更多操作（…）菜单
  • 指标：过去 24 小时的 HTTP 请求、HTTP 错误率和 HTTP P95 延迟（附迷你趋势图），以及链接到已部署模型的卡片
  • 选项卡：Overview、Monitoring、Predict 和 Logs
  • 状态消息：部署失败时显示失败原因

Overview 选项卡显示位置地图、包含可复制端点 URL 的端点卡片、API 文档链接、运行状况检查，以及显示价格、区域、CPU 和内存的部署信息卡片。Logs 选项卡显示近期日志条目，并可按严重性筛选（全部 / 错误）。Predict 选项卡提供内嵌预测面板，可直接在部署上进行测试；其文档结果选项卡提供可直接使用的 Python、JavaScript 和 cURL 代码示例，其中已填入端点 URL；对于工作区所有者，还会填入绑定的 API 密钥（参见监控）。信息对话框会列出部署属性，并允许你编辑自定义元数据。

更新 CPU 和内存#

  1. 打开状态为就绪的端点的部署页面。
  2. 点击更新配置。
  3. 选择CPU和内存，并查看显示的每小时费用。
  4. 点击更新配置。新配置就绪前，当前配置会继续提供服务。

Ultralytics Platform 部署更新 CPU 内存配置

自定义资源按运行时长计费并保持实例预热，因此也可以让 IP 摄像头持续运行，且不额外收费（请参阅后台摄像头）。恢复默认资源后会重新启用缩容至零行为，并移除后台摄像头。

临时监控数据

监控图表和示例图像是轻量级的内存中数据。停止、重启、重新部署、调整规格或替换模型都可能清除这些数据。再次启动端点不会恢复历史记录。将有用的示例保存到数据集，并等待数据导入完成后再更改端点。运行指标和日志有各自独立的历史记录保留时间。

替换模型#

替换就绪端点背后的模型，而不更改其 URL：

  1. 打开部署页面
  2. 点击替换模型
  3. 从同一工作区中选择另一个已完成的模型
  4. 可选：编辑部署名称
  5. 点击替换模型

当前模型会在替换模型启动期间继续提供服务。替换模型就绪后，流量会切换到新模型。部署 ID、URL、区域和 API 密钥保持不变；只有在你输入新名称时，显示名称才会更改。如果替换失败，之前的模型和名称仍保持有效。

替换操作必须满足以下所有条件，否则会被拒绝：

  • 部署状态为 Ready，且没有其他生命周期操作正在进行
  • 替换模型具有权重，且与部署位于同一工作区
  • 替换模型不是当前已部署的模型
每个端点对应一个模型

替换模型会从部署中移除之前的模型。每个端点只提供一个模型；如果需要同时使用两个模型，请创建另一个部署。

部署状态#

状态说明
Creating正在设置部署
Deploying容器正在启动
Ready端点已上线并开始接受请求
Stopping端点正在关闭
Stopped已暂停或启动失败；点击“开始”

对于状态为 Ready 的部署，在端点首次响应健康检查之前，页面徽标会显示 Starting；如果检查失败，则会显示 Not responding。

端点 URL#

每个端点都有唯一的 URL，例如：

https://predict-<deployment-id>-<hash>-<region>.a.run.app

带有复制按钮的 Ultralytics Platform 部署卡片端点 URL

点击复制按钮即可复制 URL。点击 API documentation 可打开该端点专属的 API 参考文档。端点提供以下路径：

路径方法说明
/predictPOST运行推理；需要部署 API 密钥
/healthGET存活检查，报告服务状态和缓存模型数量
/GET已部署服务的状态摘要
/docsGET为此部署、模型和区域生成的交互式 API 参考文档

生命周期管理#

控制端点状态：

操作说明
Start恢复已停止的端点
Stop暂停端点
删除永久移除端点

停止端点#

如果不希望端点继续接受请求，可以将其停止：

  1. 在部署页面点击 Stop deployment
  2. 端点状态会先变为“Stopping”，然后变为“Stopped”

已停止的端点：

  • 不接受请求，也不报告实时指标或健康状态
  • 不再产生运行时间费用
  • 提供服务的实例关闭时，临时监控统计数据和示例图像会丢失
  • 保留 URL、区域和绑定的 API 密钥，并且可以随时重启
  • 仍计入套餐的部署配额——删除端点即可释放配额名额

删除端点#

永久移除端点：

  1. 在部署页面打开 More actions (…) 并点击 Delete Deployment，或者点击侧边栏中该部署旁边的垃圾桶图标
  2. 点击 Delete 确认
永久性操作

删除会立即永久生效——部署不会移入回收站。删除端点会移除其服务，并释放部署配额中的一个名额。你随时可以创建新端点，但新端点会获得新的 URL。

如果模型或项目被永久删除，或者已移入回收站的模型或项目达到保留期限，相关部署也会被移除。

使用端点#

身份验证#

每个部署都绑定到模型所属工作区的一个 API 密钥。请在请求中包含该密钥：

Authorization: Bearer YOUR_API_KEY

端点只接受创建时绑定的密钥，因此其他任何密钥都无法访问端点——即使是同一工作区中的其他有效密钥也不行。若要控制绑定的密钥，请使用工作区所有者的密钥进行 API 身份验证并通过 API 部署：绑定的就是该密钥，而且你已经持有它。通过其他方式创建的部署（使用 Platform UI，或使用团队成员身份验证的 API 调用）会自动绑定所属工作区的一个有效密钥——请向工作区所有者索取密钥值，因为只有所有者能查看密钥值（请参阅 API Keys）。没有绑定密钥的团队成员仍可通过浏览器中的 Platform predict 代理运行推理。

删除绑定的密钥不会锁定端点

删除或停用绑定的 API 密钥不会撤销对端点的直接访问权限——任何持有该密钥字符串的人仍可调用端点 URL。但 Platform predict 代理会因此失效，因为它会实时检查密钥，并报告密钥已不可用。若要彻底撤销访问权限，请停止或删除部署；轮换密钥后，请重新创建端点，以便绑定新密钥。

直接向端点发送请求#

生产环境请求请直接发送到部署页面显示的 URL。这些请求不会经过 Platform API 速率限制器，因此不受每分钟 20 次预测请求的限制。但端点本身仍有容量上限：

  • 每个端点由单个实例提供服务，可同时处理的请求数量有限
  • 无法及时处理的请求会返回 429，并带有 Retry-After 标头
  • 单个请求最长可运行 1 小时，以便完成视频推理
  • 请求正文大小上限为 32 MB；更大的上传会因 413 被拒绝
  • 大于 1 KB 的响应会经过 gzip 压缩，并允许跨源浏览器请求

请求示例#

import requests

# 部署端点
url = "https://YOUR_DEPLOYMENT_URL.run.app/predict"

# 包含部署 API 密钥的标头
headers = {"Authorization": "Bearer YOUR_API_KEY"}

# 推理参数
data = {"conf": 0.25, "iou": 0.7, "imgsz": 640}

# 发送图像进行推理
with open("image.jpg", "rb") as f:
    response = requests.post(url, headers=headers, data=data, files={"file": f})

print(response.json())

请求参数#

参数类型默认值范围说明
file文件--图像或视频文件（必需，除非设置了 source）
conf浮点数0.250.01 – 1.0最低置信度阈值
iou浮点数0.70.0 – 0.95NMS IoU 阈值
imgsz整数-32 – 1280输入图像尺寸（像素）；默认使用模型的训练尺寸（如果不可用，则为 640）
normalize布尔值false-以 0 – 1 的范围返回边界框坐标
decimals整数50 – 10坐标值的小数精度
vid_stride整数1≥ 1每隔 N 帧预测一次视频；对图像无效
bits整数88, 12, 16深度图量化，仅适用于深度模型
source字符串--图像 URL 或 base64 字符串（替代 file）；通过 Platform API 发送时最多 4,096 个字符

端点会保留上次发布时的推理运行时，因此诸如训练尺寸 imgsz 默认值或上文的 vid_stride 等新行为，会在新版本发布后应用到端点，例如在你替换模型或更改 CPU 或内存之后。若要固定输入尺寸，请显式传入 imgsz。

有关 bits 如何改变返回的深度图以及如何对其解码，请参阅深度响应。

视频推理

专用端点可通过 file 参数接收图像和视频。

  • 图像格式（每个请求最大 32 MB）：AVIF、BMP、DNG、HEIC、HEIF、JP2、JPEG、JPG、MPO、PNG、TIF、TIFF、WEBP
  • 视频格式（每个请求最大 32 MB）：ASF、AVI、GIF、M4V、MKV、MOV、MP4、MPEG、MPG、TS、WEBM、WMV

结果会针对每个已处理的视频帧分别返回；深度模型仅接受图像。你也可以通过 source 参数传入公开图像 URL 或 base64 编码的图像，而不是传入 file。超大上传会因 413 被拒绝。

响应格式#

与共享推理相同，并包含特定任务的字段。

常见问题#

  • 端点数量限制取决于套餐：

    • Free：最多 3 个部署
    • Pro：最多 10 个部署
    • Enterprise：部署数量不限

    在套餐配额范围内，每个模型仍可部署到多个区域。配额计入模型所属的工作区，因此团队成员部署共享模型时会占用所有者的配额。达到上限后，系统会返回错误，要求你先删除现有部署。

  • 不可以，区域固定不变。若要更改区域：

    1. 删除现有端点
    2. 在所需区域创建新端点

    新端点会获得新的 URL。若只想更改端点后面的模型，请使用模型替换，这样 URL 会保持不变。

  • 若要覆盖全球：

    1. 部署到多个区域
    2. 使用负载均衡器或 DNS 路由
    3. 将用户路由到最近的端点

  • 冷启动时间取决于模型，以及端点是否已缩容至零；从空闲状态启动最长可能需要约一分钟。Platform 会为处于空闲状态的端点留出额外启动时间，然后才报告其运行异常。打开部署页面或重新运行其健康检查都可以唤醒空闲端点，因此在流量激增之前可以执行其中任一操作。

  • 不可以。每个部署都通过部署页面显示的生成式端点 URL 提供流量，该 URL 在部署的整个生命周期内保持稳定，包括模型替换期间。

贡献者
GLglenn-jocher23RAraimbekovm7SEsergiuwaxmann2PDpderrenger1T-t-hakobyan1

评论