跳到主要内容
训练指南章节 全部文档

Training API 参考

已注册端点、请求正文、响应、资源归属边界和错误处理。

训练指南章节

所有语言版本中的命令和代码均保持英文。请将大写占位符替换为您账户和付费作业中的实际值；请勿将真实密钥粘贴到共享笔记本或日志中。

API 资源生命周期

报价、付费作业和训练会话是不同的资源。
  1. 报价 验证配置和当前价格
  2. 作业 创建作业并完成已批准的付款
  3. 会话 选择运行环境和已包含的参考模型
  4. 准备 生成已验证的数据集清单
  5. 报告 记录真实训练和制品元数据

身份验证与请求规则

使用 HTTPS，并通过 Authorization: Bearer 发送具备 ai:training 权限范围的账户 API 密钥。发送 Accept: application/json；JSON 请求正文还需添加 Content-Type: application/json。所有资源均归属于账户。该路由组的限流为每分钟 30 个请求，另可应用其他已配置的控制。示例中的 ID 均为占位符，不是共享资源。

  • 报价 ID、作业 UUID、会话 ID、模型 ID 和制品 ID 是不同的标识符。
  • 网络中断后重试写入前，先读取当前状态。
  • 不要在 API 请求中使用公共页面文案或定价查询参数。
示例 · bash 
export TRAINING_API='https://fusionpointai.com/api/v1/training'
# Set the key securely as shown in Quickstart.
export JOB_UUID='REPLACE_WITH_YOUR_JOB_UUID'
export SESSION_ID='REPLACE_WITH_YOUR_SESSION_ID'
curl --fail-with-body --silent --show-error "$TRAINING_API/jobs" \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" -H 'Accept: application/json'

请求、响应与状态

根据符合条件的配置创建报价，再通过报价创建原生作业，并在打开会话前完成获批准的付款流程。项目端点会验证现有的付费参考模型访问权限，并请求课程或课程内容；不会创建发票或更改价格。会话响应包含配置、所选参考模型、数据集清单、报告步骤和报告对象。准备数据与提交报告是两个独立请求；作业和会话状态各自独立。

  • 项目授权需要 provider 和 reference_model_id；教师请求还需要 action 和 objective。
  • 教师示例仅限获准的训练材料；验证集和最终测试集保留在本地。
  • 旧版完成报告必须描述真实的本地制品，并通过完整性和评估检查。
示例 · text 
POST /api/v1/training/quotes
reference_model_id     required eligible integer model ID
training_plan_id       required public provider-plan integer ID
mode                   automatic | advanced
objective              required string, 10..4000 characters
language               required string, at most 120 characters
performance_criteria   required string, 10..2000 characters
student_release_slug   optional eligible slug, at most 190 characters
method                 optional eligible method, at most 80 characters
dataset_megabytes      optional integer, 1..1000000
gpu_count              optional integer, 1..128
delivery               optional: artifact | hosted
execution_target       optional: fusionpointai_hosting | customer_datacenter | colab

Availability and approved plan policies can impose narrower constraints.
Do not submit price, fixed_total, currency, price_version_id or model_training.
示例 · json 
{
  "reference_model_id": 123,
  "training_plan_id": "<INTEGER_FROM_YOUR_PROVIDER_PLAN>",
  "mode": "advanced",
  "objective": "Train a German support-message classifier.",
  "language": "German",
  "performance_criteria": "Evaluate per-class precision and recall on held-out data.",
  "student_release_slug": "<ELIGIBLE_STUDENT_RELEASE_SLUG>",
  "method": "LoRA",
  "dataset_megabytes": 8,
  "gpu_count": 1,
  "delivery": "artifact"
}
示例 · bash 
# Save the body as quote.json; replace ID placeholders with integers.
# Automatic mode omits student_release_slug and method.
curl --fail-with-body --silent --show-error "$TRAINING_API/quotes" \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  --data-binary @quote.json
# Save {"quote":"YOUR_QUOTE_UUID"} as job.json.
# Creates a native job/invoice; this is not payment confirmation.
curl --fail-with-body --silent --show-error "$TRAINING_API/jobs" \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  --data-binary @job.json
curl --fail-with-body --silent --show-error "$TRAINING_API/jobs/$JOB_UUID" \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" -H 'Accept: application/json'
示例 · text 
POST /api/v1/training/quotes: 201
{quote: UUID, currency: ISO_CODE, fixed_total: DECIMAL_STRING, expires_at: ISO_8601}

POST /api/v1/training/jobs: {"quote":"OWNED_QUOTE_UUID"}
201 for a newly created job; 200 when an accepted quote reuses its job.
Job fields:
id                job UUID
status            native job state, such as awaiting_payment
progress_percent  recorded progress, not an independent quality score
invoice_id        owned native invoice ID or null
created_at        ISO 8601 timestamp
completed_at      ISO 8601 timestamp or null
training_session  null or {id, status, step, delivery, verification}

GET /api/v1/training/jobs:
{data: JOB_ARRAY, current_page: INTEGER, last_page: INTEGER, per_page: 50, total: INTEGER}

This is a response-shape reference, not a fabricated live response.
示例 · bash 
# Save as session.json, using your paid job UUID and optional reference ID:
# {"job":"YOUR_PAID_JOB_UUID","runtime":"customer_datacenter","reference_model_id":123}
curl --fail-with-body --silent --show-error "$TRAINING_API/sessions" \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  --data-binary @session.json
curl --fail-with-body --silent --show-error "$TRAINING_API/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" -H 'Accept: application/json'
# One preparation batch; inspect progress before another request.
curl --fail-with-body --silent --show-error "$TRAINING_API/sessions/$SESSION_ID/prepare" \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H 'Accept: application/json' -H 'Content-Type: application/json' --data '{}'
示例 · text 
Session response fields (shape reference, not a fabricated live result):
id                  session UUID
job                 owned job UUID
status              preparing | ready | running | evaluating | completed | failed | cancelled
configuration       approved method, student_checkpoint, sdk_training and selected reference
reference_model_id  selected integer reference ID
expires_at          ISO 8601 access expiry
step                last reported integer step
datasets[]          {split, rows, bytes, sha256}
report              current report object; event metrics live under report.last_event.metrics
delivery            runtime_local
verification        runtime_reported
示例 · bash 
curl --fail-with-body --silent --show-error \
  "$TRAINING_API/sessions/$SESSION_ID/datasets/train" \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H 'Accept: application/x-ndjson' --output train.jsonl
# Use /datasets/validation for the other supported split.
sha256sum train.jsonl
# Compare bytes, rows and SHA-256 with the session manifest.
# For published server-side artifacts only, not the local SDK ZIP:
# GET /api/v1/training/jobs/{job}/artifacts/{file}
示例 · text 
POST /api/v1/training/sessions/{session}/events
Content-Type: application/json

state         required: running | evaluating | failed
step          required integer: 0..2000
total_steps   required integer: 1..2000
metrics       optional; only loss and eval_loss, each 0..1000000
error_code    optional: training_failed | evaluation_failed | runtime_unavailable |
              dataset_invalid | report_failed

Send actual trainer observations, never sample or invented metrics.
示例 · bash 
# Build the body from a REAL SDK report; requires jq.
jq '{artifact_name:"model-package.zip",report:.completion_report}' \
  customer-model-run-001/training-report.json > completion.json
curl --fail-with-body --silent --show-error "$TRAINING_API/sessions/$SESSION_ID/complete" \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  --data-binary @completion.json
# Cancel eligible service state, not the operating-system process:
curl --fail-with-body --silent --show-error "$TRAINING_API/sessions/$SESSION_ID/cancel" \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H 'Accept: application/json' -H 'Content-Type: application/json' --data '{}'
示例 · bash 
curl --fail-with-body --silent --show-error \
  'https://fusionpointai.com/api/v1/training/projects/authorize' \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  --data '{"provider":"openai","reference_model_id":123}'
# The response identifies the owned paid job/grant and access expiry.
示例 · bash 
curl --fail-with-body --silent --show-error \
  'https://fusionpointai.com/api/v1/training/projects/teacher' \
  -H "Authorization: Bearer $FUSIONPOINTAI_API_KEY" \
  -H 'Accept: application/json' -H 'Content-Type: application/json' \
  --data '{"provider":"openai","reference_model_id":123,"action":"lessons","objective":"Classify support messages into agreed categories.","topic":"ambiguous_requests","count":2,"approved_examples":["A reviewed support training example."]}'
# Send only explicitly approved training examples. Never send held-out rows.
# Curriculum action returns topics; lessons action returns text/topic examples.
示例 · python 
import os
from fusionpointai_training import TrainingClient

client = TrainingClient(api_key=os.environ["FUSIONPOINTAI_API_KEY"])
session = client.get_session(os.environ["FUSIONPOINTAI_SESSION_ID"])
print("Session:", session["id"])
print("Status:", session["status"])
print("Last reported step:", session["step"])
# Inspection is read-only; status and step are server-reported state.
示例 · python 
import os
from fusionpointai_training import TrainingClient

client = TrainingClient(api_key=os.environ["FUSIONPOINTAI_API_KEY"])
session = client.get_session(os.environ["FUSIONPOINTAI_SESSION_ID"])
for manifest in session["datasets"]:
    print(
        manifest["split"],
        "rows:", manifest["rows"],
        "bytes:", manifest["bytes"],
        "sha256:", manifest["sha256"],
    )
# These are server-provided manifest values, not a local integrity pass.
示例 · python 
import os
from fusionpointai_training import TrainingClient

client = TrainingClient(api_key=os.environ["FUSIONPOINTAI_API_KEY"])
session = client.get_session(os.environ["FUSIONPOINTAI_SESSION_ID"])
server_report = session.get("report")
runtime_report = server_report.get("runtime") if isinstance(server_report, dict) else None
if (
    session.get("status") == "completed"
    and isinstance(runtime_report, dict)
    and runtime_report.get("artifact_sha256") == os.environ["LOCAL_ARTIFACT_SHA256"]
    and server_report.get("delivery") == "runtime_local"
    and server_report.get("verification") == "runtime_reported"
):
    print("Server report matches the local artifact digest.")
else:
    print("Completion is not confirmed for this local artifact.")
# Reconcile by reading state; do not repeat training or invent a result.

错误与安全集成

请依据 HTTP 状态码和返回的验证详情处理错误，不要假定所有错误都是暂时性的。常见状态码包括：未认证请求为 401、访问被拒为 403、资源不存在或不属于当前账户为 404、状态不兼容为 409、输入无效为 422、请求过于频繁为 429。服务商或运行环境故障可能返回其他错误。SDK 会提供 APIError，而不会返回包含机密信息的上游原始输出。

  • 事件状态限于 running、evaluating 或 failed；指标键为 loss 和 eval_loss。
  • step 和 total_steps 的上限为 2000；total_steps 必须大于零。
  • 完成请求正文必须包含 artifact_name 及示例中列出的全部报告字段。
示例 · text 
401  Authentication missing or invalid
403  Account/key scope or access denied
404  Resource missing, non-owned or intentionally hidden
409  Invalid session transition, runtime, paid-access or model configuration
410  Writable session expired
422  Invalid request fields or completion criteria not met
429  Request rate limited
502  Upstream reference data malformed or preparation failed

Do not retry a write blindly. Read session state and inspect the response.
Keep error_code distinct from the HTTP status. Never log authorization.
示例 · text 
POST /api/v1/training/sessions/{session}/complete
artifact_name                 safe filename ending in .zip, max 160 characters
report.training_steps         integer 1..2000
report.weights_before_sha256  lowercase SHA-256 of actual pre-training weights
report.weights_after_sha256   lowercase SHA-256 of actual changed weights
report.artifact_sha256        lowercase SHA-256 of the real local ZIP
report.artifact_bytes         integer 1..107374182400
report.eval_loss_before       finite number >0 and <=1000000
report.eval_loss_after        finite number >=0 and <=1000000
report.base_repository        pinned student repository, max 255 characters
report.base_revision          lowercase immutable 40-character revision
report.method                 SFT | LoRA | QLoRA

Values must match the approved session and actual local training.
Additional report keys are rejected. This body does not upload the ZIP.
示例 · python 
import os
from fusionpointai_training import TrainingClient
from fusionpointai_training.errors import APIError

client = TrainingClient(
    api_key=os.environ["FUSIONPOINTAI_API_KEY"],
    timeout=30.0,
    max_get_retries=2,
)
try:
    session = client.get_session(os.environ["FUSIONPOINTAI_SESSION_ID"])
except APIError:
    # GET retries are bounded. Do not blindly retry a write after an error.
    print("Session inspection failed; check access and current server state.")
else:
    print("Status:", session["status"])
# Never print the API key, authorization headers, or response secrets.

API 参考

端点用途与行为
POST /api/v1/training/quotes Authorization: Bearer ai:training 验证符合条件的参考模型、方案和配置；返回报价 UUID、货币、fixed_total 和 expires_at。请使用已批准的方案和符合条件的学生模型设置，不要使用任意客户端价格。
GET /api/v1/training/jobs Authorization: Bearer ai:training 列出已认证客户的作业。请检查返回的集合和资源 ID，不要猜测数字标识符。
POST /api/v1/training/jobs Authorization: Bearer ai:training 根据有效的报价 UUID 创建归属于账户的作业。响应包含作业 ID、状态、发票 ID 和时间戳；创建作业并不能证明已付款。
GET /api/v1/training/jobs/{job} Authorization: Bearer ai:training 通过作业 UUID 读取当前账户拥有的单个作业，并查看最新进度和交付状态。
GET /api/v1/training/jobs/{job}/artifacts/{file} Authorization: Bearer ai:training 下载此账户作业中已发布的文件。本地 SDK ZIP 不会自动上传，也不一定能通过此路由获取。
POST /api/v1/training/sessions Authorization: Bearer ai:training 正文：作业 UUID、runtime，以及可选的正整数 reference_model_id。返回新建或复用的会话；只有在准备工作开始前才能更换参考模型。
GET /api/v1/training/sessions/{session} Authorization: Bearer ai:training 读取归属于当前账户的会话及其配置、数据集、报告和状态。读取状态不会启动训练。
POST /api/v1/training/sessions/{session}/prepare Authorization: Bearer ai:training 发送空 JSON 对象以请求一批有界准备数据。只要进度持续，就可在请求预算范围内重复请求，直到准备完成。
GET /api/v1/training/sessions/{session}/datasets/{split} Authorization: Bearer ai:training 以 application/x-ndjson 格式下载 train 或 validation。请根据该会话的清单验证字节、SHA-256 和行数。
POST /api/v1/training/sessions/{session}/events Authorization: Bearer ai:training 报告真实状态、step、total_steps 以及可选的 loss/eval_loss 指标。只能使用受支持的状态值和错误代码。
POST /api/v1/training/sessions/{session}/complete Authorization: Bearer ai:training 提交 artifact_name 和完整、真实的训练报告。服务会检查方法、基础模型版本、权重变化、制品摘要和评估标准。
POST /api/v1/training/sessions/{session}/cancel Authorization: Bearer ai:training 发送空 JSON 对象以取消符合条件的服务状态。必要时请自行停止独立的 GPU 进程；此操作不等于暂停或续训。
POST /api/v1/training/projects/authorize Authorization: Bearer ai:training 使用 provider 和正整数 reference_model_id 向 /api/v1/training/projects/authorize 发送 POST 请求。重新验证已认证账户对付费训练参考模型的访问权限，并返回该账户拥有的作业、授权、服务商、参考模型和到期时间。不会创建发票或更改付款。
POST /api/v1/training/projects/teacher Authorization: Bearer ai:training 向 /api/v1/training/projects/teacher 发送 POST 请求，提供 provider、reference_model_id、action（curriculum 或 lessons）、objective，以及可选的 topic、count（1–4）和最多八条 approved_examples（每条不超过 2,000 个字符）。返回主题或课程文本/主题行。只发送获准的训练材料，不要发送验证集或最终测试数据。