为国产AI API构建生产就绪评分卡

换一个 OpenAI SDK 的 base URL 很方便，但判断一个新的模型路由是否已准备好进入生产环境，就要难得多。

这个区别对于美国、英国、德国、荷兰、日本、新加坡以及其他一线/二线市场的团队很重要。开发者可以将一个 OpenAI 兼容的客户端指向 AIWave 这样的网关，在同一套 API 下测试 DeepSeek、Qwen、GLM、Kimi、ERNIE 或 MiniMax 模型。首次冒烟测试可能几分钟就能通过。但生产环境的问题不是「某一次 prompt 返回了一个看似合理的结果」，而是「这条路由是否已准备好承载客户流量，并具备明确的定价依据、数据策略、缓存假设、使用日志和回滚机制」。

我使用的模式是一张路由就绪记分卡（route readiness scorecard）。这是一个小小的审查产物，介于「API 调用成功了」和「这个模型可以服务于付费工作流」之间。

本文展示如何构建这样一张记分卡。代码示例使用环境变量存储凭证，不包含真实的密钥。

为什么记分卡比模型选择器更好

大多数模型选择器把太多决策压缩到了一个字段里：

{
  "support_summary_model": "glm-5.2"
}

对于生产环境的 SaaS 路由来说，这远远不够。你还需要知道：

• 端点形状是否与你的客户端匹配；
• 模型是否支持你的解析器所依赖的响应特性；
• 请求中是否可能包含个人数据；
• 你的客户区域策略是否允许该路由；
• 费率表是否近期核查过；
• 缓存输入是否符合预期且可见；
• 重试或降级是否会影响成本；
• 回滚是否可以不重新部署应用而发生。

记分卡使这些决策变得明确，同时也为工程、安全、产品和财务创建了一个审查界面。团队可以对某个分数持不同意见，但至少他们是在讨论具名的风险，而不是对某个模型家族模糊的偏好。

定价信息（2026年8月10日核查）

以下定价值于 2026 年 8 月 10 日通过公开的提供商页面核查。作为示例数据来源，并非永久常量。账户级定价、促销活动、路由可用性、税费和网关计费可能有所不同，因此生产系统在发布前应读取其实际计费的定价来源。

这些行说明了为什么「总 token 数」是一个弱指标。Qwen 长上下文成本取决于输入分段。GLM 成本高度依赖于稳定前缀是否会成为缓存输入。Kimi K3 对于高价值长上下文任务可能很有吸引力，但输出增长必须被控制。网关可以简化访问，但不会消除对路由级核算的需求。

从一个普通数据对象开始。将其与路由配置放在一起，像应用代码一样审查它。

route_id: support_reply_draft_v2
checked_on: 2026-08-10
gateway:
  base_url: https://aiwave.live/v1
  endpoint_family: openai_chat_completions
candidate_model:
  family: glm
  model: glm-5.2
workflow:
  task_class: support_draft
  customer_visible: true
  max_input_tokens: 24000
  max_output_tokens: 900
  requires_streaming: false
  requires_json_object: true
data_policy:
  personal_data_possible: true
  allowed_regions:
    - United States
    - United Kingdom
    - Germany
    - Netherlands
  retention_class: metadata_only
pricing:
  source_url: https://docs.z.ai/guides/overview/pricing
  input_usd_per_1m: "1.40"
  cached_input_usd_per_1m: "0.26"
  output_usd_per_1m: "4.40"
operations:
  feature_flag: ai_route_support_reply_glm52
  rollback_route: support_reply_previous_provider
  owner: platform-ai
  review_after_days: 14

金额值使用字符串类型，以便干净地往返到 Decimal。不要在记分卡中存储真实 API 密钥、支付标识符、客户邮箱、原始 prompt 或私有客户名称。

流量迁移前先给路由评分

只有当路由通过了集成、政策、成本、可观测性和运营的最低门槛时，才算就绪。评分函数可以很简单。

from dataclasses import dataclass
from decimal import Decimal

@dataclass(frozen=True)
class RouteScorecard:
    route_id: str
    endpoint_verified: bool
    behavior_probe_passed: bool
    data_policy_approved: bool
    pricing_checked_on: str
    input_usd_per_1m: Decimal
    output_usd_per_1m: Decimal
    max_input_tokens: int
    max_output_tokens: int
    max_request_usd: Decimal
    ledger_enabled: bool
    rollback_enabled: bool

def estimate_ceiling_usd(card: RouteScorecard) -> Decimal:
    input_cost = (
        Decimal(card.max_input_tokens)
        * card.input_usd_per_1m
        / Decimal(1_000_000)
    )
    output_cost = (
        Decimal(card.max_output_tokens)
        * card.output_usd_per_1m
        / Decimal(1_000_000)
    )
    return input_cost + output_cost

def readiness(card: RouteScorecard) -> dict:
    blockers = []
    if not card.endpoint_verified:
        blockers.append("endpoint_not_verified")
    if not card.behavior_probe_passed:
        blockers.append("behavior_probe_failed")
    if not card.data_policy_approved:
        blockers.append("data_policy_not_approved")
    if estimate_ceiling_usd(card) > card.max_request_usd:
        blockers.append("request_budget_exceeded")
    if not card.ledger_enabled:
        blockers.append("usage_ledger_missing")
    if not card.rollback_enabled:
        blockers.append("rollback_missing")

    return {
        "route_id": card.route_id,
        "ready": not blockers,
        "blockers": blockers,
        "estimated_ceiling_usd": str(estimate_ceiling_usd(card)),
        "pricing_checked_on": card.pricing_checked_on,
    }

这不需要成为一个复杂的优化器。目的是阻止一条有风险的路由仅仅因为一次演示成功就成为默认路径。

使用相同客户端形状运行行为探测

OpenAI 兼容 API 减少了 SDK 变动，但兼容性仍然需要验证。为你的工作流所需的确切行为运行小规模探测。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AIWAVE_API_KEY"],
    base_url=os.environ.get("AIWAVE_BASE_URL", "https://aiwave.live/v1"),
)

def probe_json_route(model: str) -> dict:
    response = client.chat.completions.create(
        model=model,
        messages=[
            {"role": "system", "content": "Return valid JSON only."},
            {"role": "user", "content": '{"status":"ready","risk":"low"}'},
        ],
        response_format={"type": "json_object"},
        temperature=0.1,
        max_tokens=80,
    )

    content = response.choices[0].message.content or ""
    return {
        "model": model,
        "has_content": bool(content.strip()),
        "has_usage": response.usage is not None,
        "content_preview": content[:120],
    }

保持探测无聊化。它们不是基准测试。它们应该捕获被拒绝的参数、缺失的 usage、空响应、流式不兼容、JSON 形状失败或账户级模型访问问题。

对于支持起草工作流，运行一个基础聊天探测和一个 JSON 探测。对于编码 Agent，添加一个工具调用探测和一个流式探测。对于长上下文路由，添加一个使用稳定前缀的缓存敏感探测，并记录缓存 token 是否在 usage 元数据中可见。

模型选择前先加入策略

不要让路由器在了解客户和数据策略之前就选择模型。一条对于非敏感内部评估可接受的路由，在包含个人数据的工作流中可能是错误的。

from dataclasses import dataclass

@dataclass(frozen=True)
class CustomerPolicy:
    region: str
    allows_personal_data_route: bool
    allowed_model_families: set[str]
    max_request_usd: Decimal

def approve_policy(
    policy: CustomerPolicy,
    model_family: str,
    has_personal_data: bool,
    estimated_usd: Decimal,
) -> tuple[bool, str]:
    if model_family not in policy.allowed_model_families:
        return False, "model_family_blocked"
    if has_personal_data and not policy.allows_personal_data_route:
        return False, "data_policy_blocked"
    if estimated_usd > policy.max_request_usd:
        return False, "budget_blocked"
    return True, "approved"

这是一线/二线买家在审查时最关心的部分。答案不应该是「提供商是 OpenAI 兼容的」。答案应该是「此工作流使用此路由，受此客户策略约束，包含此保留类别、此预算、此核查过的定价来源，以及此回滚标志」。

存储使用元数据，而非原始 prompt

路由就绪记分卡应为每个被接受的请求和每个被拒绝的请求要求一条账本记录。拒绝记录很有用，因为它们展示了政策或预算不允许的产品需求。

from datetime import datetime, timezone
import hashlib
import json

def hash_tenant(tenant_id: str) -> str:
    return hashlib.sha256(tenant_id.encode("utf-8")).hexdigest()[:16]

def ledger_row(
    tenant_id: str,
    route_id: str,
    model: str,
    policy_result: str,
    estimated_usd: Decimal,
    pricing_source: str,
    pricing_checked_on: str,
) -> dict:
    return {
        "timestamp": datetime.now(timezone.utc).isoformat(),
        "tenant_hash": hash_tenant(tenant_id),
        "route_id": route_id,
        "model": model,
        "policy_result": policy_result,
        "estimated_usd": str(estimated_usd),
        "pricing_source": pricing_source,
        "pricing_checked_on": pricing_checked_on,
        "retention_class": "metadata_only",
    }

print(json.dumps(
    ledger_row(
        tenant_id="customer-123",
        route_id="support_reply_draft_v2",
        model="glm-5.2",
        policy_result="approved",
        estimated_usd=Decimal("0.042"),
        pricing_source="https://docs.z.ai/guides/overview/pricing",
        pricing_checked_on="2026-08-10",
    ),
    indent=2,
))

元数据优先的账本有助于工程团队调试路由行为，同时不会收集超过所需的客户内容。在生产环境中添加请求 ID、重试次数、降级路由、prompt token 估算、返回的 usage、缓存 token、输出 token 和验证结果。

一个实用的评分规则

只有在硬性阻塞项通过后，才使用小的数字评分规则。

根据工作流风险设置发布阈值。内部文档的后台摘要器可能比面向客户的支持回复生成器需要更低的分数。可能处理个人数据的路由应该将策略批准、元数据仅保留和回滚作为硬性要求，而非可选加分项。

这如何应用于 AIWave

AIWave 在团队希望通过一个网关获得中国模型家族的 OpenAI 兼容访问，而非维护独立的提供商集成时很有用。这是一个集成上的优势。路由就绪记分卡将这种集成转化为一种运营实践。

例如，团队可以保持相同的 OpenAI SDK 形状，将 base_url 设置为 https://aiwave.live/v1，并为 Qwen、GLM、Kimi、DeepSeek 和 ERNIE 测试路由。记分卡然后决定哪些路由可以为哪些工作流服务：

• Qwen 路由：适用于有可见输入 token 分段的有界应用任务。
• GLM 路由：适用于可以测量缓存输入的结构化推理。
• Kimi 路由：适用于有明确输出上限的高价值长上下文工作。
• DeepSeek 路由：适用于缓存感知的规划和执行分离。
• ERNIE 路由：适用于模型行为通过与任何其他候选模型相同探测的工作负载。

要点不是为某个模型加冕。要点是让每条生产路由都能自我解释。

以下是我推荐的发布规则：

在端点探测、行为探测、策略检查、带日期的定价核查、使用账本和回滚标志全部在同一发布窗口内通过之前，中国 AI API 路由不得进入生产环境。

这条规则故意严格。它可以节省后续的时间。当客户问为什么某个工作流使用了特定模型、为什么某个请求被阻止、或者为什么在模型迁移后账单发生了变化时，答案已经在记分卡和账本中了。

OpenAI 兼容网关让实验变得更快。路由就绪让实验可以部署。

信息来源（2026年8月10日核查）

• AIWave API 文档：https://aiwave.live/docs
• AIWave 定价页面：https://aiwave.live/pricing
• QwenCloud 定价文档：https://docs.qwencloud.com/developer-guides/getting-started/pricing
• QwenCloud qwen3.7-flash 模型页面：https://www.qwencloud.com/models/qwen3.7-flash
• Z.AI 定价文档：https://docs.z.ai/guides/overview/pricing
• Kimi K3 定价文档：https://www.kimi.com/resources/kimi-k3-pricing