快速开始

从部署完成到首个查询请求跑通的最短路径——双部署模式确认、初始化、配置首个上游、创建密钥、发出请求、控制台核对

本节带你从平台部署完成的那一刻起，走通一条最短链路：确认运行环境与许可状态、初始化管理员、接入首个上游模型、创建一把 API 密钥、发出第一个查询请求，并在运营控制台看到这条请求落账。全程约六步，预计十分钟内可完成。

平台对外暴露两类接口平面，本节会同时用到：

平面	前缀	用途
数据平面	`/v1/*`	OpenAI 兼容的统一查询入口；客户应用以此发起推理请求
控制平面	`/api/v1/*`	控制台的初始化、配置、查询、对账等管理接口

下文示例中的 https://your-platform 请替换为你的平台实例统一入口地址（可在运营控制台「平台设置 · 接入参数」中查看）。

1. 确认运行环境

平台支持两种部署模式，二者功能一致、仅运行位置与隔离方式不同。开始前先确认你的实例处于哪一种模式，以及许可是否在有效期内。

部署模式	运行位置	隔离方式
私有化部署	客户自有控制环境	实例独占
SaaS 部署	供应方托管环境	VM 级逻辑隔离

调用部署与许可状态接口，确认实例「已部署 · 正常可用」且许可未失效：

curl https://your-platform/api/v1/deployment \
  -H "Cookie: <控制台会话凭证>"

响应给出部署模式、可用性二值与许可有效期：

{
  "deploy_mode": "private",
  "deploy_status": "ready",
  "license": { "valid_until": "<许可失效日>", "kill_switch": false }
}

若 deploy_status 非 ready 或 kill_switch 为 true，请先联系部署方处理许可与部署状态，再继续后续步骤。许可失效开关一旦置位，数据平面将停止受理新请求。

2. 初始化管理员

首次进入平台需建立管理员会话。登录为账号口令形式，登录成功后下发会话凭证，随后所有控制平面请求携带该凭证即可。

curl https://your-platform/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "<管理员账号>",
    "password": "<管理员口令>"
  }'

登录成功返回会话建立回执；视角（客户 Portal / 运营控制台）由平台按账户归属注入，无需在请求中声明。

{
  "session": "<会话凭证>",
  "scope": "operator",
  "account": "<账户标识>"
}

后续所有控制平面 /api/v1/* 请求都需携带上一步拿到的会话凭证。本节示例统一用 -H "Cookie: <控制台会话凭证>" 表示，请按你的客户端实际方式携带会话。可随时调用 GET /api/v1/auth/me 核对当前账户与视角。

3. 配置首个上游

平台聚合两类上游：自有供应模型（含自托管）与第三方兼容接入（OpenAI / Anthropic / Gemini 规范）。要让查询有可路由的目标，先接入至少一个上游。

curl https://your-platform/api/v1/providers \
  -H "Content-Type: application/json" \
  -H "Cookie: <控制台会话凭证>" \
  -d '{
    "name": "首个上游",
    "source": "self",
    "type": "openai-compatible",
    "models": ["<模型中性名>"],
    "group": "default",
    "priority": 1,
    "weight": 1
  }'

参数	含义
`source`	上游来源：`self`（自有供应）/ `third_party`（第三方兼容）
`models`	该上游对外提供的模型清单（统一中性名）
`group`	路由分组，决定哪些查询可命中本上游
`priority` / `weight`	路由优先级与同优先级内的加权权重

接入后做一次连通性探测，确认上游处于「已接入 · 可用」：

curl https://your-platform/api/v1/providers/<上游标识>/probe \
  -X POST \
  -H "Cookie: <控制台会话凭证>"

模型对外一律以中性名出现，上游的批发价等成本口径仅在运营控制台可见，不随数据平面 /v1/models 返回给客户应用。模型池准入门槛（智能水平指数）由平台在接入时自动判定，可在「模型接入」页查看。

4. 创建 API 密钥

客户应用调用数据平面需要一把 API 密钥。密钥按部门 / 业务线 / 成本中心建立为子账户，用量逐请求归属到对应子账户分账。

curl https://your-platform/api/v1/keys \
  -H "Content-Type: application/json" \
  -H "Cookie: <控制台会话凭证>" \
  -d '{
    "name": "首个业务线",
    "dimension": "business-line",
    "model_scope": [],
    "expires_at": null
  }'

其中 dimension 为归属维度（部门 / 业务线 / 成本中心），model_scope 为允许调用的模型范围（留空即全部），expires_at 为过期日期（留空即永不过期）。新建密钥摘要中包含密钥本体，仅在创建时返回一次，请妥善保存：

{
  "api_key_id": "<子账户标识>",
  "key": "tsxt-************************",
  "status": "active"
}

全部子账户共用一层汇总信用额度。达到额度上限时，全部密钥会一并暂停，并在密钥列表与额度管理页给出预警与暂停状态。具体额度与预警阈值以服务协议与控制台显示为准。

5. 发出首个查询请求

带上刚创建的 API 密钥，调用数据平面统一查询入口。该入口 OpenAI 兼容，可直接复用既有 SDK——只需将基址指向平台入口、把鉴权头换成平台密钥。

curl https://your-platform/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tsxt-************************" \
  -d '{
    "model": "<模型中性名>",
    "messages": [
      { "role": "user", "content": "你好，帮我做一次简单的连通性自检。" }
    ],
    "stream": false
  }'

请求进入平台后，依次经过路由、缓存检查点、安全护栏三层中间件治理，再转发至最合适的上游模型。响应为 OpenAI 兼容的 chat.completion，其中 usage 扩展字段携带本次请求的计量信息：

{
  "id": "<响应标识>",
  "object": "chat.completion",
  "model": "<实际路由的上游模型中性名>",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "<生成内容>" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 24,
    "total_tokens": 42,
    "cached_input_tokens": 0,
    "price_tier": "input-miss-no-thinking",
    "thinking": false
  }
}

usage 中的 price_tier 标明本次落入的计量档（输入命中 / 未命中 × thinking / no-thinking + 输出，共六档），是后续计费与对账的依据。计量采用统一计价词元口径，缓存命中时对应档单价更低，thinking 档相对溢价——具体单价以服务协议与控制台显示为准。

若需在发请求前预估词元数与适用档位，可调用统一计价词元计数接口 POST /v1/token-count，对给定文本按平台口径返回各档词元数，便于客户侧复算核对计费。训练期内首次接入的密钥享折扣计价，相关标识会随逐条记录与结算单一并呈现。

6. 在控制台核对

回到运营控制台，确认刚才这条请求已落账。逐条调用记录与监控汇总取自同一份用量底座，逐条之和等于分项之和、等于汇总。

查询逐条调用记录（默认时间倒序，可按子账户、模型筛选）：

curl "https://your-platform/api/v1/usage/records?page=1&page_size=20" \
  -H "Cookie: <控制台会话凭证>"

响应含顶部汇总与逐条数组，你应能找到刚才那条请求：

{
  "total": 1,
  "page": 1,
  "page_size": 20,
  "summary": {
    "total_input_tokens": 18,
    "total_output_tokens": 24,
    "total_amount": "<金额合计（含税）>"
  },
  "items": [
    {
      "call_id": "<调用标识>",
      "api_key_id": "<子账户标识>",
      "timestamp": "<调用时间>",
      "routed_model": "<本次路由选定的上游模型中性名>",
      "complexity": "simple",
      "cache_hit": false,
      "thinking": false,
      "input_tokens": 18,
      "output_tokens": 24,
      "price_tier": "input-miss-no-thinking",
      "charge_amount": "<该次金额（含税）>",
      "guardrail_result": "pass"
    }
  ]
}

也可在「请求监控」页（GET /api/v1/monitor/overview）查看查询量、复杂度分布与模型选择分布等聚合视图。

逐条记录中的 input_tokens / output_tokens 可经第 5 步提到的计数接口对相应文本复算核对，确保计量可验证。同一条请求在「用量明细」「概览」「请求监控」三处看到的数字相互对得上。

下一步

首个请求跑通后，可按需深入各能力域：

中间件管道与扩展点 SDK：三类中间件的编排顺序、前置 / 后置 Hook 对称管道与扩展点接入规范
多上游模型接入：自有与第三方接入流程、模型池准入门槛、路由优先级与权重配置
路由小模型微调：微调工具链、客户部署实例内训练与数据隔离口径
部署与许可：双部署模式部署指南、许可有效期与失效开关
数据安全：数据留存、个人信息策略与退出导出清单
API 参考：统一查询入口与运营管理接口的完整端点契约