USML 开放平台文档

USML (Unified Service Machine Learning) 提供了一套高性能的机器学习模型托管与推理服务。本文档将指导您如何在私有环境中部署服务节点，并通过 RESTful API 进行业务集成。

当前环境： 您正在访问 https://usml.hetao.us 的官方文档。所有示例代码均基于此域名生成。

服务端部署配置

我们推荐使用 Docker Compose 进行一键编排。以下配置包含了核心服务、Redis 缓存以及 Prometheus 监控探针。

version: '3.8'

services:
  usml-core:
    image: usml/core-server:v2.4.0
    container_name: usml_api
    restart: always
    ports:
      - "8080:8080"
    environment:
      - NODE_ENV=production
      - DB_HOST=postgres
      - REDIS_URL=redis://redis:6379
    depends_on:
      - postgres
      - redis
    networks:
      - usml-net

  redis:
    image: redis:6.2-alpine
    command: redis-server --appendonly yes
    volumes:
      - redis_data:/data
    networks:
      - usml-net

networks:
  usml-net:
    driver: bridge

volumes:
  redis_data:

Nginx 网关配置

生产环境请务必配置 SSL 证书，并开启 Gzip 压缩以提高传输效率。

server {
    listen 443 ssl http2;
    server_name usml.hetao.us;

    # SSL 证书配置
    ssl_certificate /etc/nginx/certs/usml.crt;
    ssl_certificate_key /etc/nginx/certs/usml.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    
    # 开启 Gzip
    gzip on;
    gzip_types application/json application/javascript text/css;

    # API 反向代理
    location /api/ {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        
        # 增加超时时间以适应长连接推理任务
        proxy_read_timeout 300s;
        proxy_connect_timeout 75s;
    }
}

身份认证 (Authentication)

平台采用标准的 OAuth 2.0 风格鉴权。所有受保护的接口都需要在 Header 中携带 Authorization: Bearer <token>。

POST /api/v1/auth/token

使用 AppID 和 Secret 换取访问令牌。

curl -X POST https://usml.hetao.us/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "usml_8829102",
    "secret": "sk_live_99283..."
  }'

import requests

url = "https://usml.hetao.us/api/v1/auth/token"
payload = {
    "app_id": "usml_8829102",
    "secret": "sk_live_99283..."
}

response = requests.post(url, json=payload)
print(response.json())

const axios = require('axios');

async function getToken() {
  const { data } = await axios.post('https://usml.hetao.us/api/v1/auth/token', {
    app_id: 'usml_8829102',
    secret: 'sk_live_99283...'
  });
  console.log(data);
}

响应参数

`access_token`string	用于接口调用的凭证，请妥善保管。
`expires_in`int	Token 有效期（秒），默认 7200。

文件服务 (Object Storage)

POST /api/v1/files/upload

支持多文件上传，单文件最大限制 100MB。

import requests

url = "https://usml.hetao.us/api/v1/files/upload"
headers = {"Authorization": "Bearer eyJhbGciOi..."}
files = [
    ('files', ('data.csv', open('data.csv', 'rb'), 'text/csv')),
    ('files', ('model.onnx', open('model.onnx', 'rb'), 'application/octet-stream'))
]

resp = requests.post(url, headers=headers, files=files)

Webhooks 事件回调

当异步任务完成时，服务器会向您配置的 URL 发送 POST 请求。

Payload 数据结构 (TypeScript)

interface WebhookEvent {
  event_id: string;      // 事件唯一ID
  event_type: "task.completed" | "task.failed";
  timestamp: number;     // 毫秒级时间戳
  data: {
    task_id: string;
    result_url?: string; // 成功时返回结果下载链接
    error_code?: number; // 失败时返回错误码
    metrics: {           // 性能指标
      inference_time: number;
      memory_usage: number;
    }
  }
}