zhao.zhu/yolov26_3d
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

单目3D初始代码

Browse Source
This commit is contained in:
zhao.zhu
2026-06-24 09:35:46 +08:00
commit 04a5895b6b
1153 changed files with 340700 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

416
docs/en/platform/deploy/endpoints.md Executable file
View File

@@ -0,0 +1,416 @@
---
comments: true
description: Deploy YOLO models to dedicated endpoints in 43 global regions with auto-scaling and monitoring on Ultralytics Platform.
keywords: Ultralytics Platform, deployment, endpoints, YOLO, production, scaling, global regions
---
# Dedicated Endpoints
[Ultralytics Platform](https://platform.ultralytics.com) enables deployment of YOLO models to dedicated endpoints in 43 global regions. Each endpoint is a single-tenant service with auto-scaling, a unique endpoint URL, and independent monitoring.
![Ultralytics Platform Model Deploy Tab With Region Map And Table](https://cdn.jsdelivr.net/gh/ultralytics/assets@main/docs/platform/model-deploy-tab-with-region-map-and-table.avif)
## Create Endpoint
### From the Deploy Tab
Deploy a model from its `Deploy` tab:
1. Navigate to your model
2. Click the **Deploy** tab
3. Select a region from the region table (sorted by latency from your location)
4. Click **Deploy** on the region row
The deployment name is auto-generated from the model name and region city (e.g., `yolo11n-iowa`).
### From the Deployments Page
Create a deployment from the global `Deploy` page in the sidebar:
1. Click **New Deployment**
2. Select a model from the model selector
3. Select a region from the map or table
4. Optionally customize the deployment name and resources
5. Click **Deploy Model**
![Ultralytics Platform New Deployment Dialog With Model Selector And Region Map](https://cdn.jsdelivr.net/gh/ultralytics/assets@main/docs/platform/new-deployment-dialog-with-model-selector-and-region-map.avif)
### Deployment Lifecycle
```mermaid
stateDiagram-v2
[*] --> Creating: Deploy
Creating --> Deploying: Container starting
Deploying --> Ready: Health check passed
Ready --> Stopping: Stop
Stopping --> Stopped: Stopped
Stopped --> Ready: Start
Ready --> [*]: Delete
Stopped --> [*]: Delete
Creating --> Failed: Error
Deploying --> Failed: Error
Failed --> [*]: Delete
```
### Region Selection
Choose from 43 regions worldwide. The interactive region map and table show:
- **Region pins**: Color-coded by latency (green < 100ms, yellow < 200ms, red > 200ms)
- **Deployed regions**: Highlighted with a "Deployed" badge
- **Deploying regions**: Animated pulse indicator
- **Bidirectional highlighting**: Hover on the map highlights the table row, and vice versa
![Ultralytics Platform Deploy Tab Region Latency Table Sorted By Latency](https://cdn.jsdelivr.net/gh/ultralytics/assets@main/docs/platform/deploy-tab-region-latency-table-sorted-by-latency.avif)
The region table on the model `Deploy` tab includes:
| Column | Description |
| ------------ | ---------------------------------------- |
| **Location** | City and country with flag icon |
| **Zone** | Region identifier |
| **Latency** | Measured ping time (median of 3 pings) |
| **Distance** | Distance from your location in km |
| **Actions** | Deploy button or "Deployed" status badge |
!!! note "New Deployment Dialog"
The `New Deployment` dialog (from the global `Deploy` page) shows a simpler region table with only Location, Latency, and Select columns.
!!! tip "Choose Wisely"
Select the region closest to your users for lowest latency. Use the **Rescan** button to re-measure latency from your current location.
## Available Regions
=== "Americas (14)"
| Zone | Location |
| ----------------------- | ---------------------- |
| us-central1 | Iowa, USA |
| us-east1 | South Carolina, USA |
| us-east4 | Northern Virginia, USA |
| us-east5 | Columbus, USA |
| us-south1 | Dallas, USA |
| us-west1 | Oregon, USA |
| us-west2 | Los Angeles, USA |
| us-west3 | Salt Lake City, USA |
| us-west4 | Las Vegas, USA |
| northamerica-northeast1 | Montreal, Canada |
| northamerica-northeast2 | Toronto, Canada |
| northamerica-south1 | Queretaro, Mexico |
| southamerica-east1 | Sao Paulo, Brazil |
| southamerica-west1 | Santiago, Chile |
=== "Europe (13)"
| Zone | Location |
| ----------------- | ---------------------- |
| europe-west1 | St. Ghislain, Belgium |
| europe-west2 | London, UK |
| europe-west3 | Frankfurt, Germany |
| europe-west4 | Eemshaven, Netherlands |
| europe-west6 | Zurich, Switzerland |
| europe-west8 | Milan, Italy |
| europe-west9 | Paris, France |
| europe-west10 | Berlin, Germany |
| europe-west12 | Turin, Italy |
| europe-north1 | Hamina, Finland |
| europe-north2 | Stockholm, Sweden |
| europe-central2 | Warsaw, Poland |
| europe-southwest1 | Madrid, Spain |
=== "Asia-Pacific (12)"
| Zone | Location |
| -------------------- | ---------------------- |
| asia-east1 | Changhua, Taiwan |
| asia-east2 | Kowloon, Hong Kong |
| asia-northeast1 | Tokyo, Japan |
| asia-northeast2 | Osaka, Japan |
| asia-northeast3 | Seoul, South Korea |
| asia-south1 | Mumbai, India |
| asia-south2 | Delhi, India |
| asia-southeast1 | Jurong West, Singapore |
| asia-southeast2 | Jakarta, Indonesia |
| asia-southeast3 | Bangkok, Thailand |
| australia-southeast1 | Sydney, Australia |
| australia-southeast2 | Melbourne, Australia |
=== "Middle East & Africa (4)"
| Zone | Location |
| ------------- | -------------------------- |
| africa-south1 | Johannesburg, South Africa |
| me-central1 | Doha, Qatar |
| me-central2 | Dammam, Saudi Arabia |
| me-west1 | Tel Aviv, Israel |
## Endpoint Configuration
### New Deployment Dialog
The `New Deployment` dialog provides:
| Setting | Description | Default |
| ------------------- | ---------------------------- | ------- |
| **Model** | Select from completed models | - |
| **Region** | Deployment region | - |
| **Deployment Name** | Auto-generated, editable | - |
| **CPU Cores** | CPU allocation (1-8) | 1 |
| **Memory (GB)** | Memory allocation (1-32 GB) | 2 |
![Ultralytics Platform New Deployment Dialog Resources Panel Expanded](https://cdn.jsdelivr.net/gh/ultralytics/assets@main/docs/platform/new-deployment-dialog-resources-panel-expanded.avif)
Resource settings are available under the collapsible **Resources** section. Deployments use scale-to-zero by default (min instances = 0, max instances = 1) — you only pay for active inference time.
!!! note "Auto-Generated Names"
The deployment name is automatically generated from the model name and region city (e.g., `yolo11n-iowa`). If you deploy the same model to the same region again, a numeric suffix is added (e.g., `yolo11n-iowa-2`).
### Deploy Tab (Quick Deploy)
When deploying from the model's `Deploy` tab, endpoints are created with default resources (1 CPU, 2 GB memory) with scale-to-zero enabled. The deployment name is auto-generated.
## Manage Endpoints
### View Modes
The deployments list supports three view modes:
| Mode | Description |
| ----------- | --------------------------------------------------------- |
| **Cards** | Full detail cards with logs, code examples, predict panel |
| **Compact** | Grid of smaller cards with key metrics |
| **Table** | DataTable with sortable columns and search |
![Ultralytics Platform Deploy Tab Active Deployments Cards View](https://cdn.jsdelivr.net/gh/ultralytics/assets@main/docs/platform/deploy-tab-active-deployments-cards-view.avif)
### Deployment Card (Cards View)
Each deployment card in the cards view shows:
- **Header**: Name, region flag, status badge, start/stop/delete buttons
- **Endpoint URL**: Copyable URL with link to API docs
- **Metrics**: Request count (24h), P95 latency, error rate
- **Health check**: Live health indicator with latency and manual refresh
- **Tabs**: `Logs`, `Code`, and `Predict`
The `Logs` tab shows recent log entries with severity filtering (All / Errors). The `Code` tab shows ready-to-use code examples in Python, JavaScript, and cURL with your actual endpoint URL and API key. The `Predict` tab provides an inline predict panel for testing directly on the deployment.
### Deployment Statuses
| Status | Description |
| ------------- | --------------------------------------- |
| **Creating** | Deployment is being set up |
| **Deploying** | Container is starting |
| **Ready** | Endpoint is live and accepting requests |
| **Stopping** | Endpoint is shutting down |
| **Stopped** | Endpoint is paused (no billing) |
| **Failed** | Deployment failed (see error message) |
### Endpoint URL
Each endpoint has a unique URL, for example:
```
https://predict-abc123.run.app
```
![Ultralytics Platform Deployment Card Endpoint Url With Copy Button](https://cdn.jsdelivr.net/gh/ultralytics/assets@main/docs/platform/deployment-card-endpoint-url-with-copy-button.avif)
Click the copy button to copy the URL. Click the docs icon to view the auto-generated API documentation for the endpoint.
## Lifecycle Management
Control your endpoint state:
```mermaid
graph LR
R[Ready] -->|Stop| S[Stopped]
S -->|Start| R
R -->|Delete| D[Deleted]
S -->|Delete| D
style R fill:#4CAF50,color:#fff
style S fill:#9E9E9E,color:#fff
style D fill:#F44336,color:#fff
```
| Action | Description |
| ---------- | ------------------------------- |
| **Start** | Resume a stopped endpoint |
| **Stop** | Pause the endpoint (no billing) |
| **Delete** | Permanently remove endpoint |
### Stop Endpoint
Stop an endpoint to pause billing:
1. Click the pause icon on the deployment card
2. Endpoint status changes to "Stopping" then "Stopped"
Stopped endpoints:
- Don't accept requests
- Don't incur charges
- Can be restarted anytime
### Delete Endpoint
Permanently remove an endpoint:
1. Click the delete (trash) icon on the deployment card
2. Confirm deletion in the dialog
!!! warning "Permanent Action"
Deletion is immediate and permanent. You can always create a new endpoint.
## Using Endpoints
### Authentication
Each deployment is created with an API key from your account. Include it in requests:
```bash
Authorization: Bearer YOUR_API_KEY
```
The API key prefix is displayed on the deployment card footer for identification. Generate keys from [API Keys](../account/api-keys.md).
### No Rate Limits
Dedicated endpoints are **not subject to the Platform API rate limits**. Requests go directly to your dedicated service, so throughput is limited only by your endpoint's CPU, memory, and scaling configuration. This is a key advantage over [shared inference](inference.md), which is rate-limited to 20 requests/min per API key.
### Request Example
=== "Python"
```python
import requests
# Deployment endpoint
url = "https://predict-abc123.run.app/predict"
# Headers with your deployment API key
headers = {"Authorization": "Bearer YOUR_API_KEY"}
# Inference parameters
data = {"conf": 0.25, "iou": 0.7, "imgsz": 640}
# Send image for inference
with open("image.jpg", "rb") as f:
response = requests.post(url, headers=headers, data=data, files={"file": f})
print(response.json())
```
=== "JavaScript"
```javascript
// Build form data with image and parameters
const formData = new FormData();
formData.append("file", fileInput.files[0]);
formData.append("conf", "0.25");
formData.append("iou", "0.7");
formData.append("imgsz", "640");
// Send image for inference
const response = await fetch(
"https://predict-abc123.run.app/predict",
{
method: "POST",
headers: { Authorization: "Bearer YOUR_API_KEY" },
body: formData,
}
);
const result = await response.json();
console.log(result);
```
=== "cURL"
```bash
curl -X POST \
"https://predict-abc123.run.app/predict" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@image.jpg" \
-F "conf=0.25" \
-F "iou=0.7" \
-F "imgsz=640"
```
### Request Parameters
| Parameter | Type | Default | Description |
| ----------- | ------ | ------- | ----------------------------- |
| `file` | file | - | Image file (required) |
| `conf` | float | 0.25 | Minimum confidence threshold |
| `iou` | float | 0.7 | NMS IoU threshold |
| `imgsz` | int | 640 | Input image size |
| `normalize` | string | - | Return normalized coordinates |
### Response Format
Same as [shared inference](inference.md#response) with task-specific fields.
## Pricing
Dedicated endpoints bill based on:
| Component | Rate |
| ------------ | -------------------- |
| **CPU** | Per vCPU-second |
| **Memory** | Per GB-second |
| **Requests** | Per million requests |
!!! tip "Cost Optimization"
- Use scale-to-zero for development endpoints
- Set appropriate max instances
- Monitor usage in the [Monitoring](monitoring.md) dashboard
- Review costs in [Settings > Billing](../account/billing.md)
## FAQ
### How many endpoints can I create?
Endpoint limits depend on plan:
- **Free**: Up to 3 deployments
- **Pro**: Up to 10 deployments
- **Enterprise**: Unlimited deployments
Each model can still be deployed to multiple regions within your plan quota.
### Can I change the region after deployment?
No, regions are fixed. To change regions:
1. Delete the existing endpoint
2. Create a new endpoint in the desired region
### How do I handle multi-region deployment?
For global coverage:
1. Deploy to multiple regions
2. Use a load balancer or DNS routing
3. Route users to the nearest endpoint
### What's the cold start time?
Cold start time depends on model size and whether the container is already cached in the region. Typical ranges:
| Scenario | Cold Start |
| ------------------- | -------------- |
| Cached container | ~5-15 seconds |
| First deploy/region | ~15-45 seconds |
The health check uses a 55-second timeout to accommodate worst-case cold starts.
### Can I use custom domains?
Custom domains are coming soon. Currently, endpoints use platform-generated URLs.

205
docs/en/platform/deploy/index.md Executable file
View File

@@ -0,0 +1,205 @@
---
comments: true
description: Learn about model deployment options in Ultralytics Platform including inference testing, dedicated endpoints, and monitoring dashboards.
keywords: Ultralytics Platform, deployment, inference, endpoints, monitoring, YOLO, production, cloud deployment
---
# Deployment
[Ultralytics Platform](https://platform.ultralytics.com) provides comprehensive deployment options for putting your YOLO models into production. Test models with browser-based inference, deploy to dedicated endpoints across 43 global regions, and monitor performance in real-time.
## Overview
The Deployment section helps you:
- **Test** models directly in the browser with the `Predict` tab
- **Deploy** to dedicated endpoints in 43 global regions
- **Monitor** request metrics, logs, and health checks
- **Scale** automatically with traffic (including scale-to-zero)
![Ultralytics Platform Deploy Page World Map With Overview Cards](https://cdn.jsdelivr.net/gh/ultralytics/assets@main/docs/platform/deploy-page-world-map-with-overview-cards.avif)
## Deployment Options
Ultralytics Platform offers multiple deployment paths:
| Option | Description | Best For |
| --------------------------------------- | -------------------------------------------------------- | ----------------------- |
| **[Predict Tab](inference.md)** | Browser-based inference with image, webcam, and examples | Development, validation |
| **Shared Inference** | Multi-tenant service across 3 regions | Light usage, testing |
| **[Dedicated Endpoints](endpoints.md)** | Single-tenant services across 43 regions | Production, low latency |
## Workflow
```mermaid
graph LR
A[✅ Test] --> B[⚙️ Configure]
B --> C[🌐 Deploy]
C --> D[📊 Monitor]
style A fill:#4CAF50,color:#fff
style B fill:#2196F3,color:#fff
style C fill:#FF9800,color:#fff
style D fill:#9C27B0,color:#fff
```
| Stage | Description |
| ------------- | ------------------------------------------------------------------------ |
| **Test** | Validate model with the [`Predict` tab](inference.md) |
| **Configure** | Select region, resources, and deployment name |
| **Deploy** | Create a dedicated endpoint from the [`Deploy` tab](endpoints.md) |
| **Monitor** | Track requests, latency, errors, and logs in [Monitoring](monitoring.md) |
## Architecture
### Shared Inference
The shared inference service runs in 3 key regions, automatically routing requests based on your data region:
```mermaid
graph TB
User[User Request] --> API[Platform API]
API --> Router{Region Router}
Router -->|US users| US["US Predict Service<br/>Iowa"]
Router -->|EU users| EU["EU Predict Service<br/>Belgium"]
Router -->|AP users| AP["AP Predict Service<br/>Hong Kong"]
style User fill:#f5f5f5,color:#333
style API fill:#2196F3,color:#fff
style Router fill:#FF9800,color:#fff
style US fill:#4CAF50,color:#fff
style EU fill:#4CAF50,color:#fff
style AP fill:#4CAF50,color:#fff
```
| Region | Location |
| ------ | ----------------------- |
| US | Iowa, USA |
| EU | Belgium, Europe |
| AP | Hong Kong, Asia-Pacific |
### Dedicated Endpoints
Deploy to 43 regions worldwide on Ultralytics Cloud:
- **Americas**: 14 regions
- **Europe**: 13 regions
- **Asia-Pacific**: 12 regions
- **Middle East & Africa**: 4 regions
Each endpoint is a single-tenant service with:
- Dedicated compute resources (configurable CPU and memory)
- Auto-scaling (scale-to-zero when idle)
- Unique endpoint URL
- Independent monitoring, logs, and health checks
## Deployments Page
Access the global deployments page from the sidebar under `Deploy`. This page shows:
- **World map** with deployed region pins (interactive map)
- **Overview cards**: Total Requests (24h), Active Deployments, Error Rate (24h), P95 Latency (24h)
- **Deployments list** with three view modes: cards, compact, and table
- **New Deployment** button to create endpoints from any completed model
![Ultralytics Platform Deploy Page Overview Cards And Deployments List](https://cdn.jsdelivr.net/gh/ultralytics/assets@main/docs/platform/deploy-page-overview-cards-and-deployments-list.avif)
!!! info "Automatic Polling"
The page polls every 30 seconds for metric updates. When deployments are in a transitional state (creating, deploying, stopping), polling increases to every 2-3 seconds for near-instant feedback.
## Key Features
### Global Coverage
Deploy close to your users with 43 regions covering:
- North America, South America
- Europe, Middle East, Africa
- Asia Pacific, Oceania
### Auto-Scaling
Endpoints scale automatically:
- **Scale to zero**: No cost when idle (default)
- **Scale up**: Handle traffic spikes automatically
!!! tip "Cost Savings"
Scale-to-zero is enabled by default (min instances = 0). You only pay for active inference time.
### Low Latency
Dedicated endpoints provide:
- Cold start: ~5-15 seconds (cached container), up to ~45 seconds (first deploy)
- Warm inference: 50-200ms (model dependent)
- Regional routing for optimal performance
### Health Checks
Each running deployment includes an automatic health check with:
- Live status indicator (healthy/unhealthy)
- Response latency display
- Auto-retry when unhealthy (polls every 20 seconds)
- Manual refresh button
## Quick Start
Deploy a model in under 2 minutes:
1. Train or upload a model to a project
2. Go to the model's **Deploy** tab
3. Select a region from the latency table
4. Click **Deploy** — your endpoint is live
!!! example "Quick Deploy"
```
Model → Deploy tab → Select region → Click Deploy → Endpoint URL ready
```
Once deployed, use the endpoint URL with your API key to send inference requests from any application.
## Quick Links
- [**Inference**](inference.md): Test models in browser
- [**Endpoints**](endpoints.md): Deploy dedicated endpoints
- [**Monitoring**](monitoring.md): Track deployment performance
## FAQ
### What's the difference between shared and dedicated inference?
| Feature | Shared | Dedicated |
| ----------- | --------------- | -------------- |
| **Latency** | Variable | Consistent |
| **Cost** | Pay per request | Pay for uptime |
| **Scale** | Limited | Configurable |
| **Regions** | 3 | 43 |
| **URL** | Generic | Custom |
### How long does deployment take?
Dedicated endpoint deployment typically takes 1-2 minutes:
1. Image pull (~30s)
2. Container start (~30s)
3. Health check (~30s)
### Can I deploy multiple models?
Yes, each model can have multiple endpoints in different regions. There's no limit on total endpoints (subject to your plan).
### What happens when an endpoint is idle?
With scale-to-zero enabled:
- Endpoint scales down after inactivity
- First request triggers cold start
- Subsequent requests are fast
First requests after an idle period trigger a cold start.

416
docs/en/platform/deploy/inference.md Executable file
View File

@@ -0,0 +1,416 @@
---
comments: true
description: Learn how to test YOLO models with the Ultralytics Platform inference API including browser testing and programmatic access.
keywords: Ultralytics Platform, inference, API, YOLO, object detection, prediction, testing
---
# Inference
[Ultralytics Platform](https://platform.ultralytics.com) provides an inference API for testing trained models. Use the browser-based `Predict` tab for quick validation or the [REST API](../api/index.md#models-api) for programmatic access.
![Ultralytics Platform Model Predict Tab With Detections Overlay](https://cdn.jsdelivr.net/gh/ultralytics/assets@main/docs/platform/model-predict-tab-with-detections-overlay.avif)
## Predict Tab
Every model includes a `Predict` tab for browser-based inference:
1. Navigate to your model
2. Click the **Predict** tab
3. Upload an image, use an example, or open your webcam
4. View predictions instantly with bounding box overlays
![Ultralytics Platform Predict Tab Image Upload Dropzone](https://cdn.jsdelivr.net/gh/ultralytics/assets@main/docs/platform/predict-tab-image-upload-dropzone.avif)
### Input Methods
The predict panel supports multiple input methods:
| Method | Description |
| ------------------ | ---------------------------------------------------- |
| **Image upload** | Drag and drop or click to upload an image |
| **Example images** | Click built-in examples (dataset images or defaults) |
| **Webcam capture** | Live camera feed with single-frame capture |
```mermaid
graph LR
A[Upload Image] --> D[Auto-Inference]
B[Example Image] --> D
C[Webcam Capture] --> D
D --> E[Results + Overlays]
style D fill:#2196F3,color:#fff
style E fill:#4CAF50,color:#fff
```
### Upload Image
Drag and drop or click to upload:
- **Supported formats**: JPEG, PNG, WebP, AVIF, HEIC, JP2, TIFF, BMP, DNG, MPO
- **Max size**: 10MB
- **Auto-inference**: Results appear automatically after upload
!!! info "Auto-Inference"
The predict panel runs inference automatically when you upload an image, select an example, or capture a webcam frame. No button click is needed.
### Example Images
The predict panel shows example images from your model's linked dataset. If no dataset is linked, default examples are used:
| Image | Content |
| ------------ | -------------------------- |
| `bus.jpg` | Street scene with vehicles |
| `zidane.jpg` | Sports scene with people |
For OBB models, aerial images of boats and airports are shown instead.
!!! tip "Preloaded Images"
Example images are preloaded when the page loads, so clicking an example triggers near-instant inference with no download wait.
### Webcam
Click the webcam card to start a live camera feed:
1. Grant camera permission when prompted
2. Click the video preview to capture a frame
3. Inference runs automatically on the captured frame
4. Click again to restart the webcam
### View Results
Inference results display:
- **Bounding boxes** with class labels as SVG overlays
- **Confidence scores** for each detection
- **Class colors** from your dataset's color palette (or the Ultralytics default palette)
- **Speed breakdown**: Preprocess, inference, postprocess, and network time
![Ultralytics Platform Predict Tab Results With Detections And Speed Stats](https://cdn.jsdelivr.net/gh/ultralytics/assets@main/docs/platform/predict-tab-results-with-detections-and-speed-stats.avif)
The results panel shows:
| Field | Description |
| ------------------- | ------------------------------------------------ |
| **Detections list** | Each detection with class name and confidence |
| **Speed stats** | Preprocess, inference, postprocess, network (ms) |
| **JSON response** | Raw API response in a code block |
## Inference Parameters
Adjust detection behavior with parameters in the collapsible **Parameters** section:
![Ultralytics Platform Predict Tab Parameters Sliders](https://cdn.jsdelivr.net/gh/ultralytics/assets@main/docs/platform/predict-tab-parameters-sliders.avif)
| Parameter | Range | Default | Description |
| -------------- | -------------- | ------- | -------------------------------------- |
| **Confidence** | 0.01-1.0 | 0.25 | Minimum confidence threshold |
| **IoU** | 0.0-0.95 | 0.70 | NMS IoU threshold |
| **Image Size** | 320, 640, 1280 | 640 | Input resize dimension (button toggle) |
!!! note "Auto-Rerun"
Changing any parameter automatically re-runs inference on the current image with a 500ms debounce. No need to re-upload.
### Confidence Threshold
Filter predictions by confidence:
- **Higher (0.5+)**: Fewer, more certain predictions
- **Lower (0.1-0.25)**: More predictions, some noise
- **Default (0.25)**: Balanced for most use cases
### IoU Threshold
Control Non-Maximum Suppression:
- **Higher (0.7+)**: Allow more overlapping boxes
- **Lower (0.3-0.5)**: Merge nearby detections more aggressively
- **Default (0.70)**: Balanced NMS behavior for most use cases
## Deployment Predict
Each running [dedicated endpoint](endpoints.md) includes a `Predict` tab directly on its deployment card. This uses the deployment's own inference service rather than the shared predict service, letting you test your deployed endpoint from the browser.
## REST API
Access inference programmatically:
### Authentication
Include your API key in requests:
```bash
Authorization: Bearer YOUR_API_KEY
```
!!! warning "API Key Required"
To run inference from your own scripts, notebooks, or apps, include an API key. Generate one in [`Settings`](../account/api-keys.md) (API Keys section on the Profile tab).
### Endpoint
```
POST https://platform.ultralytics.com/api/models/{modelId}/predict
```
### Request
=== "Python"
```python
import requests
url = "https://platform.ultralytics.com/api/models/MODEL_ID/predict"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
files = {"file": open("image.jpg", "rb")}
data = {"conf": 0.25, "iou": 0.7, "imgsz": 640}
response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())
```
=== "cURL"
```bash
curl -X POST \
"https://platform.ultralytics.com/api/models/MODEL_ID/predict" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@image.jpg" \
-F "conf=0.25" \
-F "iou=0.7" \
-F "imgsz=640"
```
=== "JavaScript"
```javascript
const formData = new FormData();
formData.append("file", fileInput.files[0]);
formData.append("conf", "0.25");
formData.append("iou", "0.7");
formData.append("imgsz", "640");
const response = await fetch(
"https://platform.ultralytics.com/api/models/MODEL_ID/predict",
{
method: "POST",
headers: { Authorization: "Bearer YOUR_API_KEY" },
body: formData,
}
);
const result = await response.json();
console.log(result);
```
![Ultralytics Platform Predict Tab Code Examples Python Tab](https://cdn.jsdelivr.net/gh/ultralytics/assets@main/docs/platform/predict-tab-code-examples-python-tab.avif)
### Response
```json
{
"images": [
{
"shape": [1080, 1920],
"results": [
{
"class": 0,
"name": "person",
"confidence": 0.92,
"box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
},
{
"class": 2,
"name": "car",
"confidence": 0.87,
"box": { "x1": 400, "y1": 200, "x2": 600, "y2": 350 }
}
],
"speed": {
"preprocess": 1.2,
"inference": 12.5,
"postprocess": 2.3
}
}
],
"metadata": {
"imageCount": 1,
"functionTimeCall": 0.018,
"model": "model.pt",
"version": {
"ultralytics": "8.4.14",
"torch": "2.6.0",
"torchvision": "0.21.0",
"python": "3.13.0"
}
}
}
```
![Ultralytics Platform Predict Tab Json Response View](https://cdn.jsdelivr.net/gh/ultralytics/assets@main/docs/platform/predict-tab-json-response-view.avif)
### Response Fields
| Field | Type | Description |
| ------------------------------- | ------ | --------------------------------- |
| `images` | array | List of processed images |
| `images[].shape` | array | Image dimensions [height, width] |
| `images[].results` | array | List of detections |
| `images[].results[].name` | string | Class name |
| `images[].results[].confidence` | float | Detection confidence (0-1) |
| `images[].results[].box` | object | Bounding box coordinates |
| `images[].speed` | object | Processing times in milliseconds |
| `metadata` | object | Request metadata and version info |
### Task-Specific Responses
Response format varies by task:
=== "Detection"
```json
{
"class": 0,
"name": "person",
"confidence": 0.92,
"box": {"x1": 100, "y1": 50, "x2": 300, "y2": 400}
}
```
=== "Segmentation"
```json
{
"class": 0,
"name": "person",
"confidence": 0.92,
"box": {"x1": 100, "y1": 50, "x2": 300, "y2": 400},
"segments": [[100, 50], [150, 60], ...]
}
```
=== "Pose"
```json
{
"class": 0,
"name": "person",
"confidence": 0.92,
"box": {"x1": 100, "y1": 50, "x2": 300, "y2": 400},
"keypoints": [
{"x": 200, "y": 75, "conf": 0.95},
...
]
}
```
=== "Classification"
```json
{
"results": [
{"class": 0, "name": "cat", "confidence": 0.95},
{"class": 1, "name": "dog", "confidence": 0.03}
]
}
```
=== "OBB"
```json
{
"class": 0,
"name": "ship",
"confidence": 0.89,
"box": {"x1": 100, "y1": 50, "x2": 300, "y2": 400},
"obb": {"x1": 105, "y1": 48, "x2": 295, "y2": 55, "x3": 290, "y3": 395, "x4": 110, "y4": 402}
}
```
## Rate Limits
Shared inference is rate-limited to **20 requests/min per API key**. When throttled, the API returns `429` with a `Retry-After` header. See the full [rate limit reference](../api/index.md#rate-limits) for all endpoint categories.
!!! tip "Need More Throughput?"
Deploy a [dedicated endpoint](endpoints.md) for **unlimited** inference with no rate limits, predictable throughput, and consistent low-latency responses. For local inference, see the [Predict mode guide](../../modes/predict.md).
## Error Handling
Common error responses:
| Code | Message | Solution |
| ---- | --------------- | ------------------------------------------------------------------------------------ |
| 400 | Invalid image | Check file format |
| 401 | Unauthorized | Verify API key |
| 404 | Model not found | Check model ID |
| 429 | Rate limited | Wait and retry, or use a [dedicated endpoint](endpoints.md) for unlimited throughput |
| 500 | Server error | Retry request |
## FAQ
### Can I run inference on video?
The API accepts individual frames. For video:
1. Extract frames locally
2. Send each frame to the API
3. Aggregate results
For real-time video, consider deploying a [dedicated endpoint](endpoints.md).
### How do I get the annotated image?
The API returns JSON predictions. To visualize:
1. Use predictions to draw boxes locally
2. Use Ultralytics `plot()` method:
```python
from ultralytics import YOLO
model = YOLO("yolo26n.pt")
results = model("image.jpg")
results[0].save("annotated.jpg")
```
See the [Predict mode documentation](../../modes/predict.md) for the full results API and visualization options.
### What's the maximum image size?
- **Upload limit**: 10MB
- **Recommended**: <5MB for fast inference
- **Auto-resize**: Images are resized to the selected `Image Size` parameter
Large images are automatically resized while preserving aspect ratio.
### Can I run batch inference?
The current API processes one image per request. For batch:
1. Send concurrent requests
2. Use a dedicated endpoint for higher throughput
3. Consider local inference for large batches
!!! example "Batch Inference with Python"
```python
import concurrent.futures
import requests
url = "https://predict-abc123.run.app/predict"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
images = ["img1.jpg", "img2.jpg", "img3.jpg"]
def predict(image_path):
with open(image_path, "rb") as f:
return requests.post(url, headers=headers, files={"file": f}).json()
with concurrent.futures.ThreadPoolExecutor(max_workers=4) as executor:
results = list(executor.map(predict, images))
```

355
docs/en/platform/deploy/monitoring.md Executable file
View File

@@ -0,0 +1,355 @@
---
comments: true
description: Monitor deployed YOLO models on Ultralytics Platform with real-time metrics, request logs, and performance dashboards.
keywords: Ultralytics Platform, monitoring, metrics, logs, deployment, performance, YOLO, observability
---
# Monitoring
[Ultralytics Platform](https://platform.ultralytics.com) provides monitoring for deployed endpoints. Track request metrics, view logs, and check health status with automatic polling.
![Ultralytics Platform Deploy Page Overview Cards And World Map](https://cdn.jsdelivr.net/gh/ultralytics/assets@main/docs/platform/deploy-page-overview-cards-and-world-map.avif)
## Deployments Dashboard
The `Deploy` page in the sidebar serves as the monitoring dashboard for all your deployments. It combines the world map, overview metrics, and deployment management in one view. See [Dedicated Endpoints](endpoints.md) for creating and managing deployments.
```mermaid
graph TB
subgraph Dashboard
Map[World Map] --- Cards[Overview Cards]
Cards --- List[Deployments List]
end
subgraph "Per Deployment"
Metrics[Metrics Row]
Health[Health Check]
Logs[Logs Tab]
Code[Code Tab]
Predict[Predict Tab]
end
List --> Metrics
List --> Health
List --> Logs
List --> Code
List --> Predict
style Dashboard fill:#f5f5f5,color:#333
style Map fill:#2196F3,color:#fff
style Cards fill:#FF9800,color:#fff
style List fill:#4CAF50,color:#fff
```
### Overview Cards
Four summary cards at the top of the page show:
![Ultralytics Platform Deploy Page Four Overview Cards](https://cdn.jsdelivr.net/gh/ultralytics/assets@main/docs/platform/deploy-page-four-overview-cards.avif)
| Metric | Description |
| ------------------------ | ----------------------------- |
| **Total Requests (24h)** | Requests across all endpoints |
| **Active Deployments** | Currently running endpoints |
| **Error Rate (24h)** | Percentage of failed requests |
| **P95 Latency (24h)** | 95th percentile response time |
!!! warning "Error Rate Alert"
The error rate card highlights in red when the rate exceeds 5%. Check the `Logs` tab on individual deployments to diagnose errors.
### World Map
The interactive world map shows:
- **Region pins** for all 43 available regions
- **Green pins** for deployed regions
- **Animated blue pins** for regions with active deployments in progress
- **Pin size** varies based on deployment status and latency
![Ultralytics Platform Deploy Page World Map With Deployed Regions](https://cdn.jsdelivr.net/gh/ultralytics/assets@main/docs/platform/deploy-page-world-map-with-deployed-regions.avif)
### Deployments List
Below the overview cards, the deployments list shows all endpoints across your projects. Use the view mode toggle to switch between:
| View | Description |
| ----------- | ---------------------------------------------------------------------------- |
| **Cards** | Full detail cards with metrics, logs, code, and predict tabs |
| **Compact** | Grid of smaller cards (1-4 columns) with key metrics |
| **Table** | DataTable with sortable columns: Name, Region, Status, Requests, P95, Errors |
!!! tip "Real-Time Updates"
The dashboard polls every 30 seconds for metric updates. When deployments are in a transitional state (creating, deploying), polling increases to every 3 seconds. Click the refresh button for immediate updates.
## Per-Deployment Metrics
Each deployment card (in cards view) shows real-time metrics:
### Metrics Row
| Metric | Description |
| --------------- | ----------------------------- |
| **Requests** | Request count (24h) with icon |
| **P95 Latency** | 95th percentile response time |
| **Error Rate** | Percentage of failed requests |
Metrics are fetched from the sparkline API endpoint and refresh every 60 seconds.
### Health Check
Running deployments show a health check indicator:
| Indicator | Meaning |
| ----------------- | -------------------------------- |
| **Green heart** | Healthy — shows response latency |
| **Red heart** | Unhealthy — shows error message |
| **Spinning icon** | Health check in progress |
Health checks auto-retry every 20 seconds when unhealthy. Click the refresh icon to manually trigger a health check. The health check uses a 55-second timeout to accommodate cold starts on scale-to-zero endpoints.
![Ultralytics Platform Deployment Card Health Check Healthy With Latency](https://cdn.jsdelivr.net/gh/ultralytics/assets@main/docs/platform/deployment-card-health-check-healthy-with-latency.avif)
!!! info "Cold Start Tolerance"
The health check uses a 55-second timeout to account for cold starts on scale-to-zero endpoints (up to ~45 seconds in worst case). Once the endpoint warms up, health checks complete in milliseconds.
## Logs
Each deployment card includes a `Logs` tab for viewing recent log entries:
![Ultralytics Platform Deployment Card Logs Tab With Severity Filter](https://cdn.jsdelivr.net/gh/ultralytics/assets@main/docs/platform/deployment-card-logs-tab-with-severity-filter.avif)
### Log Entries
Each log entry shows:
| Field | Description |
| ------------- | --------------------------------------- |
| **Severity** | Color-coded bar (see below) |
| **Timestamp** | Request time (local format) |
| **Message** | Log content |
| **HTTP info** | Status code and latency (if applicable) |
=== "Severity Levels"
Filter logs by severity using the filter buttons:
| Level | Color | Description |
| ------------ | -------- | ------------------- |
| **DEBUG** | Gray | Debug messages |
| **INFO** | Blue | Normal requests |
| **WARNING** | Yellow | Non-critical issues |
| **ERROR** | Red | Failed requests |
| **CRITICAL** | Dark Red | Critical failures |
=== "Log Controls"
| Control | Description |
| ----------- | ----------------------------------- |
| **Errors** | Filter to ERROR and WARNING entries |
| **All** | Show all log entries |
| **Copy** | Copy all visible logs to clipboard |
| **Refresh** | Reload log entries |
The UI shows the 20 most recent entries. The API defaults to 50 entries per request (max 200).
!!! tip "Debugging Workflow"
When investigating errors: first click **Errors** to filter to ERROR and WARNING entries, then review timestamps and HTTP status codes. Copy logs to clipboard for sharing with your team.
## Code Examples
Each deployment card includes a `Code` tab showing ready-to-use API code with your actual endpoint URL and API key:
=== "Python"
```python
import requests
# Deployment endpoint
url = "https://predict-abc123.run.app/predict"
# Headers with your deployment API key
headers = {"Authorization": "Bearer YOUR_API_KEY"}
# Inference parameters
data = {"conf": 0.25, "iou": 0.7, "imgsz": 640}
# Send image for inference
with open("image.jpg", "rb") as f:
response = requests.post(url, headers=headers, data=data, files={"file": f})
print(response.json())
```
=== "JavaScript"
```javascript
// Build form data with image and parameters
const formData = new FormData();
formData.append("file", fileInput.files[0]);
formData.append("conf", "0.25");
formData.append("iou", "0.7");
formData.append("imgsz", "640");
// Send image for inference
const response = await fetch(
"https://predict-abc123.run.app/predict",
{
method: "POST",
headers: { Authorization: "Bearer YOUR_API_KEY" },
body: formData,
}
);
const result = await response.json();
console.log(result);
```
=== "cURL"
```bash
# Send image for inference
curl -X POST "https://predict-abc123.run.app/predict" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@image.jpg" \
-F "conf=0.25" \
-F "iou=0.7" \
-F "imgsz=640"
```
!!! note "Auto-Populated Credentials"
When viewing the `Code` tab in the platform, your actual endpoint URL and API key are automatically filled in. Copy the code and run it directly. See [API Keys](../account/api-keys.md) to generate a key.
## Deployment Predict
The `Predict` tab on each deployment card provides an inline predict panel — the same interface as the model's `Predict` tab, but running inference through the deployment endpoint instead of the shared service. This is useful for testing a deployed endpoint directly from the browser. See [Inference](inference.md) for parameter details and response formats.
## API Endpoints
### Monitoring Overview
```
GET /api/monitoring
```
Returns aggregated metrics for all deployments owned by the authenticated user. Workspace-aware via optional `owner` query parameter.
### Deployment Metrics
```
GET /api/deployments/{deploymentId}/metrics?sparkline=true&range=24h
```
Returns sparkline data and summary metrics for a specific deployment. Refresh interval: 60 seconds.
| Parameter | Type | Description |
| ----------- | ------ | --------------------------------------------- |
| `sparkline` | bool | Include sparkline data |
| `range` | string | Time range: `1h`, `6h`, `24h`, `7d`, or `30d` |
### Deployment Logs
```
GET /api/deployments/{deploymentId}/logs?limit=50&severity=ERROR,WARNING
```
Returns recent log entries with optional severity filter and pagination.
| Parameter | Type | Description |
| ----------- | ------ | --------------------------------------------- |
| `limit` | int | Max entries to return (default: 50, max: 200) |
| `severity` | string | Comma-separated severity filter |
| `pageToken` | string | Pagination token from previous response |
### Deployment Health
```
GET /api/deployments/{deploymentId}/health
```
Returns health check status with response latency.
```json
{
"healthy": true,
"status": 200,
"latencyMs": 142
}
```
## Performance Optimization
Use monitoring data to optimize your deployments:
=== "High Latency"
If latency is too high:
1. Check instance count (may need more)
2. Verify model size is appropriate
3. Consider a closer region
4. Check image sizes being sent
!!! example "Reducing Latency"
Switch from `imgsz=1280` to `imgsz=640` for a ~4x speedup with minimal accuracy loss for most use cases. Deploy to a region closer to your users for lower network latency.
=== "High Error Rate"
If errors are occurring:
1. Review error logs in the `Logs` tab
2. Check request format (multipart form required)
3. Verify API key is valid
4. Check rate limits
=== "Scaling Issues"
If hitting capacity:
1. Consider multiple regions
2. Optimize request batching
3. Increase CPU and memory resources
## FAQ
### How long is data retained?
| Data Type | Retention |
| ----------- | --------- |
| **Metrics** | 30 days |
| **Logs** | 7 days |
### Can I set up external monitoring?
Yes, endpoint URLs work with external monitoring tools:
- Uptime monitoring (Pingdom, UptimeRobot)
- APM tools (Datadog, New Relic)
- Custom health checks via the `/health` endpoint
### How accurate are the latency numbers?
Latency metrics measure:
- **P50**: Median response time
- **P95**: 95th percentile
- **P99**: 99th percentile
These represent server-side processing time, not including network latency to your users.
### Why are my metrics delayed?
Metrics have a ~2 minute delay due to:
- Metrics aggregation pipeline
- Aggregation windows
- Dashboard caching
For real-time debugging, check logs which are near-instant.
### Can I monitor multiple endpoints together?
Yes, the deployments page shows all endpoints with aggregated overview cards. Use the table view to compare performance across deployments.