AI 模型平台

受众：开发者 / 运维开发者摘要：spring-open-module-ai 是独立 AI 模型平台模块，负责 Provider 运营、模型目录、价格与 quota、凭证治理、模型网关和用量观测。

定位

spring-open-module-ai 独立承载 AI 模型供应商平台，不放入 Open Platform 子域。模块名称保持 spring-open-module-ai，内部再按职责划分 platform、gateway、provider、model、usage、billing 等子域。

本模块借鉴 NewAPI 的核心运营思路，包括 Provider / Channel 配置、模型倍率、分组倍率、quota 计量、用量事件、优先级与权重路由、凭证池、健康治理和兼容网关协议；实现方式完全使用项目现有模块边界、Provider SPI、Service contract、MyBatis-Plus、Liquibase 和统一后台路由规范，不直接复制外部项目源码。

子域	职责
`platform`	平台控制面，承载 Provider、凭证池、模型目录、价格、套餐、成本毛利、路由、质量和对账
`gateway`	模型调用面，承载 OpenAI Compatible、Claude / Anthropic Messages、Codex / Responses API 兼容入口
`provider`	Provider 配置覆盖、凭证治理、健康评分、冷却和路由候选
`model`	模型目录、模型别名、能力标签、开放状态和模型级 fallback
`usage`	AI 调用事件、token、路由、凭证、trace 和 quota 快照
`billing`	AI token 预占、结算、失败释放和倍率计算；正式发布默认开启，缺少真实账户时拒绝调用

模块边界

项	当前值
Maven 模块	`spring-open-modules/spring-open-module-ai`
Java 包	`com.springopen.module.ai`
配置前缀	`spring.open.ai.*`
后台权限	`ai:platform:view`、`ai:platform:update`、`ai:gateway:view`、`ai:skill:view`、`ai:skill:update`
后台平台 API	`/api/v1/admin/ai/platform/**`
开放控制面 API	`/api/v1/ai/platform/**`
模型网关 API	`/api/v1/ai/gateway/**`
模型调用底座	`spring-open-starter-ai-model`
Skill 底座	`spring-open-starter-ai-skill`

spring-open-starter-ai-model 只负责模型调用抽象和 Provider SPI。spring-open-starter-ai-skill 只负责 Skill 文档解析、发现、激活匹配和安全资源策略，不直接执行脚本或业务工具。AI 模块负责运营数据、数据库覆盖、凭证治理、Skill 数据库态版本、用量、quota、成本和控制面 API。跨模块共用能力通过 spring-open-core-runtime、spring-open-core-secret、spring-open-core-entitlement、spring-open-core-cashier 等底座协作，不反向依赖 Open Platform 业务模块。

API 路由

开放控制面用于读取平台公开元数据：

API	说明
`GET /api/v1/ai/platform/overview`	查询 AI 平台概览
`GET /api/v1/ai/platform/providers`	查询 Provider 配置实例，隐藏 API Key 明文
`GET /api/v1/ai/platform/models`	查询可用模型目录、平台别名和 operation 能力画像，支持查询参数筛选
`GET /api/v1/ai/platform/prices`	查询模型价格目录和成本字段
`GET /api/v1/ai/platform/packages`	查询 AI 套餐目录
`GET /api/v1/ai/platform/profit`	查询成本毛利看板
`GET /api/v1/ai/platform/routing`	查询 Provider 路由策略

平台概览会返回 Provider 列表和模型目录的发现 contract：

providerQueryParameters：Provider 列表支持的查询参数，便于前端和开发者工具动态渲染筛选器。
providerOperationFilters：当前网关已知 operation 集合，和 Provider / 模型能力过滤复用同一套能力映射。
modelQueryParameters：模型目录支持的查询参数，便于前端和开发者工具动态渲染模型筛选器。
modelOperationFilters：当前网关已知 operation 集合，和模型目录 operation 过滤复用同一套能力映射。
providerFilterOptions：按当前 Provider 配置聚合出的筛选可选值，例如 Provider 名称、实际类型、渠道类型、能力画像、relay 画像和能力标签。
modelFilterOptions：按当前模型目录聚合出的筛选可选值，例如 Provider 名称、模型名、平台别名和能力标签。
providerCount、enabledProviderCount、defaultProviderCount、databaseOverrideProviderCount：Provider 运营统计。
modelCount、enabledModelCount、openModelCount、databaseOverrideModelCount：模型目录运营统计。
providerOperationCounts、modelOperationCounts：按 operation 聚合的 Provider / 模型可用数量。

后台控制面用于运营配置和巡检：

API	说明
`GET /api/v1/admin/ai/platform/overview`	后台 AI 平台概览，权限 `ai:platform:view`
`GET /api/v1/admin/ai/platform/providers`	查询 Provider 覆盖配置
`PUT /api/v1/admin/ai/platform/providers/{providerName}`	保存 Provider 覆盖配置，权限 `ai:platform:update`
`PUT /api/v1/admin/ai/platform/providers/status`	批量启停 Provider，权限 `ai:platform:update`
`POST /api/v1/admin/ai/platform/providers/probe`	批量探测 Provider 连通性，权限 `ai:platform:update`
`POST /api/v1/admin/ai/platform/providers/{providerName}/probe`	探测 Provider 连通性，权限 `ai:platform:update`
`POST /api/v1/admin/ai/platform/providers/{providerName}/models/sync`	从 Provider 同步模型目录，权限 `ai:platform:update`
`GET /api/v1/admin/ai/platform/providers/{providerName}/credentials`	查询 Provider 凭证池
`GET /api/v1/admin/ai/platform/provider-credentials/health`	查询 Provider 凭证健康概览
`PUT /api/v1/admin/ai/platform/providers/{providerName}/credentials/{credentialName}/cooldown`	保存 Provider 凭证人工冷却，权限 `ai:platform:update`
`PUT /api/v1/admin/ai/platform/providers/{providerName}/credentials/{credentialName}`	保存 Provider 凭证，权限 `ai:platform:update`
`DELETE /api/v1/admin/ai/platform/providers/{providerName}/credentials/{credentialName}`	删除 Provider 凭证，权限 `ai:platform:update`
`GET /api/v1/admin/ai/platform/gateway-keys`	查询后台 AI Gateway Key
`GET /api/v1/admin/ai/platform/gateway-keys/usage/summary`	查询 AI Gateway Key 用量汇总
`POST /api/v1/admin/ai/platform/gateway-keys`	创建后台 AI Gateway Key，权限 `ai:platform:update`
`PUT /api/v1/admin/ai/platform/gateway-keys/status`	批量启停后台 AI Gateway Key，权限 `ai:platform:update`
`PUT /api/v1/admin/ai/platform/gateway-keys/{keyId}`	保存后台 AI Gateway Key，权限 `ai:platform:update`
`POST /api/v1/admin/ai/platform/gateway-keys/{keyId}/rotate`	轮换后台 AI Gateway Key，权限 `ai:platform:update`
`PUT /api/v1/admin/ai/platform/gateway-keys/{keyId}/quota`	保存后台 AI Gateway Key 已用 quota，权限 `ai:platform:update`
`DELETE /api/v1/admin/ai/platform/gateway-keys/{keyId}`	删除后台 AI Gateway Key，权限 `ai:platform:update`
`GET /api/v1/admin/ai/platform/models`	查询后台模型目录，支持按 Provider、模型、capability、operation 和开放状态筛选
`PUT /api/v1/admin/ai/platform/models`	保存模型目录覆盖，权限 `ai:platform:update`
`GET /api/v1/admin/ai/platform/prices`	查询后台价格目录
`PUT /api/v1/admin/ai/platform/prices`	保存模型价格，权限 `ai:platform:update`
`GET /api/v1/admin/ai/platform/quota/group-ratios`	查询后台 quota 分组倍率
`PUT /api/v1/admin/ai/platform/quota/group-ratios/{groupCode}`	保存 quota 分组倍率，权限 `ai:platform:update`
`GET /api/v1/admin/ai/platform/quota/model-ratios`	查询后台 quota 模型倍率
`PUT /api/v1/admin/ai/platform/quota/model-ratios`	保存 quota 模型倍率，权限 `ai:platform:update`
`GET /api/v1/admin/ai/platform/packages`	查询后台套餐目录
`GET /api/v1/admin/ai/platform/profit`	查询后台成本毛利
`GET /api/v1/admin/ai/platform/reconciliation`	查询 AI 用量对账
`GET /api/v1/admin/ai/platform/usage/summary`	查询 AI 用量汇总
`GET /api/v1/admin/ai/platform/usage/events`	分页查询 AI 用量事件明细
`GET /api/v1/admin/ai/platform/quality`	查询 AI 平台质量评测
`GET /api/v1/admin/ai/platform/production-checks`	分页查询 AI 上线检测运行记录
`GET /api/v1/admin/ai/platform/production-checks/latest`	查询最近一次 AI 上线检测摘要
`GET /api/v1/admin/ai/platform/production-checks/{checkRunId}`	查询 AI 上线检测详情，包含完整详情 JSON
`POST /api/v1/admin/ai/platform/production-checks/run`	主动运行一次 AI 上线检测，权限 `ai:platform:update`
`POST /api/v1/admin/ai/platform/gateway-smoke/run`	主动运行一次 AI Gateway 真实 smoke，权限 `ai:platform:update`
`GET /api/v1/admin/ai/platform/skills`	查询内置和数据库态 AI Skill，权限 `ai:skill:view`
`POST /api/v1/admin/ai/platform/skills`	导入 `SKILL.md`，可选立即发布，权限 `ai:skill:update`
`PUT /api/v1/admin/ai/platform/skills/{skillName}/status`	启用或停用数据库态 AI Skill，权限 `ai:skill:update`
`GET /api/v1/admin/ai/platform/skills/{skillName}/versions`	查询 AI Skill 版本，权限 `ai:skill:view`
`POST /api/v1/admin/ai/platform/skills/{skillName}/versions/{versionId}/publish`	发布指定 AI Skill 版本，权限 `ai:skill:update`
`GET /api/v1/admin/ai/platform/skills/run-logs`	查询 AI Skill 运行日志，权限 `ai:skill:view`
`GET /api/v1/admin/ai/platform/routing`	查询后台路由策略
`PUT /api/v1/admin/ai/platform/routing/providers/{providerName}`	保存 Provider 路由策略，权限 `ai:platform:update`

Provider 列表支持以下查询参数，开放控制面和后台控制面语义一致：

keyword：在 Provider 名称、实际类型、展示名、baseURL、能力画像和 fallback Provider 中做模糊查询。
providerName、providerType：按配置实例名或实际 Provider 类型精确筛选。
capability：按 Provider capability 筛选，兼容 operation 对 capability 的映射别名。
operation、operationSupported：按网关 operation 能力筛选；operationSupported=false 可反查会被该 operation 过滤的 Provider。
channelType、capabilityProfile、relayProfile：按渠道类型、能力画像和 relay 画像筛选，例如筛出 NewAPI / OpenRouter 这类聚合网关入口。
enabled、defaultProvider、databaseOverride：按启用状态、默认 Provider 或数据库覆盖状态筛选。

模型网关提供常见开发者工具兼容面：

API	说明
`GET /api/v1/ai/gateway/status`	查询网关状态、生产开关、Provider 健康、韧性快照和模型发现 contract
`GET /api/v1/ai/gateway/models`	OpenAI Compatible `/models`，兼容 `/v1/models`，支持 keyword / provider / model / capability / operation 查询，额外返回 capabilities、supported_operations、filtered_operations 和 operation_profiles
`POST /api/v1/ai/gateway/chat/completions`	OpenAI Compatible Chat Completions 普通 / 流式响应
`GET /api/v1/ai/gateway/claude/v1/models`	Claude / Anthropic Models，支持同一套模型筛选查询
`POST /api/v1/ai/gateway/claude/v1/messages`	Claude / Anthropic Messages 普通 / 流式响应
`POST /api/v1/ai/gateway/claude/v1/messages/count_tokens`	Claude / Anthropic Messages token 计数，使用本地 token estimator 预估输入 token，不触发上游模型调用
`GET /api/v1/ai/gateway/codex/v1/models`	Codex / Responses API 模型列表，支持同一套模型筛选查询；兼容 `GET /api/v1/ai/gateway/codex/models`
`POST /api/v1/ai/gateway/codex/v1/responses`	Codex / Responses API 普通 / 流式响应；兼容 `POST /api/v1/ai/gateway/codex/responses`

Claude / Anthropic Messages 入口会在协议转换层保留请求参数：stop_sequences 映射为 OpenAI Compatible stop，metadata、thinking 和其它未显式建模字段进入统一请求参数映射，由 starter Provider 透传给 NewAPI / OpenAI Compatible / account-pool 上游。流式响应侧会把上游推理增量按客户端协议输出：OpenAI Compatible 使用 delta.reasoning_content，Claude / Anthropic Messages 使用 thinking content block 与 thinking_delta。OpenAI Compatible chat/completions 还会保留上游实际 model、完整 choices[]、choice index、content_filter_results、顶层 prompt_filter_results、message / delta 级 refusal、annotations、audio，显式返回的 delta.role，choice 级 logprobs、usage token 明细，例如 prompt_tokens_details、completion_tokens_details、input_tokens_details 和 output_tokens_details，并保留顶层 system_fingerprint / service_tier，便于运营侧观察真实命中模型、多候选内容、多候选序号、安全过滤结果、响应注解、音频响应画像、token 概率、缓存 token、推理 token、输入 / 输出 token 细节和服务侧响应画像。Provider 仍保持协议中立，只读取最终 baseURL、apiKey、路径和参数模板 / 覆盖配置。

网关状态的模型发现 contract 还会返回：

modelDiscoveryFilterOptions：按当前运行时模型元数据聚合出的模型发现筛选可选值。
modelDiscoveryModelCount、modelDiscoveryEnabledModelCount：运行时模型发现数量统计。
modelDiscoveryOperationCounts：按 operation 聚合的运行时模型发现能力覆盖数量。

网关状态还会返回生产开关信号，便于后台状态卡片、外部监控和上线前检查读取同一份事实：

moduleEnabled：AI 模块总开关。
platformEnabled：AI 平台控制面开关。
gatewayEnabled / enabled：AI Gateway 调用面开关，enabled 保留为既有网关状态字段。
keyAuthEnabled：Gateway Key 鉴权是否启用。
rateLimitEnabled：网关限流是否启用。
billingEnabled：AI 计费预占 / 结算是否启用。
rejectMissingQuotaAccount：开启计费后，缺少 quota 账户时是否拒绝请求。
realtimeEnabled：Realtime 入口是否启用。
distributedHealthEnabled：Provider / 凭证健康聚合是否启用。

OpenAI Compatible 工具的 base URL 配置为：

text

https://<host>/api/v1/ai/gateway

如果客户端要求 base URL 已包含 OpenAI 协议版本，也可以使用 https://<host>/api/v1/ai/gateway/v1；两种前缀都会返回同一套 OpenAI Compatible 模型列表和调用结构。

Claude / Anthropic compatible 工具的 base URL 配置为：

text

https://<host>/api/v1/ai/gateway/claude

Codex / Responses compatible 工具的 base URL 配置为：

text

https://<host>/api/v1/ai/gateway/codex

如果客户端不会自动追加协议版本，也可以使用 https://<host>/api/v1/ai/gateway/codex/v1；两种前缀都会路由到同一套 Codex / Responses API 处理器。

数据模型

AI 模块迁移文件位于：

text

spring-open-modules/spring-open-module-ai/src/main/resources/db/changelog/migrations/
├── 0000_00_00_417000_module_ai_create_tables.xml
└── 0000_00_00_417100_module_ai_seed_data.xml

表	说明
`ai_provider_config`	Provider 数据库覆盖配置，包含启停、Provider 类型、baseURL、模型、fallback、优先级、权重、成本和 API Key 密文
`ai_provider_credential`	Provider 上游凭证池，包含凭证名称、来源类型、baseURL、API Key 密文、优先级、权重、options 和公开 metadata
`ai_credential_health_snapshot`	凭证健康快照，记录健康分、窗口请求、成功 / 失败 / 限流、TTFT、冷却和最近错误
`ai_model_catalog`	模型目录覆盖，包含官方模型名、开放状态、展示名、平台别名、fallback 模型、能力和上下文信息
`ai_model_price`	模型售价和成本覆盖，按 Provider + 模型维护每百万 token 价格
`ai_group_ratio`	quota 分组倍率，默认 seed 提供 `default` 分组
`ai_model_ratio`	模型倍率、输出 token 倍率和固定单次 quota
`ai_usage_event`	AI 用量事件，固化 Provider、模型、路由、凭证、token、成本、quota、trace 和耗时快照
`ai_gateway_key`	AI Gateway Key，保存 hash、脱敏前缀、scope、IP / 模型 / Provider 白名单、quota 上限、Key 级限流策略和最近使用信息
`ai_platform_check_run`	AI 平台上线检测运行记录，保存质量评分、生产就绪评分、Provider 探测摘要、阻断项、详情 JSON 和执行耗时
`ai_skill_definition`	AI Skill 定义，保存名称、状态、描述、风险等级、scope、tag 和当前发布版本
`ai_skill_version`	AI Skill 版本，保存 `SKILL.md` 原文、instructions、资源 / 脚本清单和 checksum
`ai_skill_run_log`	AI Skill 运行日志，记录 runKey、traceId、用户、状态、token、耗时和错误摘要

Provider 配置

平台 Provider 配置来自两层：

本地配置：spring.open.ai.model.providers.*
数据库覆盖：ai_provider_config

AiPlatformProviderService 读取两层配置并合并展示。后台保存 Provider 时只保存数据库覆盖，不修改本地配置文件。API Key 使用 spring.open.ai.secret.encryption-key 通过 Secret 底座保护落库，响应只返回 apiKeyConfigured。未显式配置专用加密 key 时，启动期按显式专用 → 数据库 spring.open.ai.secret.encryption-key → 数据库共享 spring.application.secret（首启自动播种，多实例共库收敛一致）→ 本地派生顺序收敛；更换生效密钥会使已加密的存量凭证不可解密，需重新录入。

示例：

yaml

spring:
  open:
    ai:
      secret:
        encryption-key: ${SPRING_OPEN_AI_SECRET_ENCRYPTION_KEY:}
      model:
        default-provider: openai-compatible
        providers:
          simulated:
            provider: simulated
            enabled: ${SPRING_OPEN_AI_MODEL_PROVIDERS_SIMULATED_ENABLED:true}
            model: simulated-default
          openai:
            provider: openai-compatible
            enabled: ${SPRING_OPEN_AI_MODEL_PROVIDERS_OPENAI_ENABLED:false}
            model: ${OPENAI_MODEL:}
            base-url: https://api.openai.com/v1
            api-key: ${OPENAI_API_KEY:}
          newapi:
            provider: newapi
            enabled: ${SPRING_OPEN_AI_MODEL_PROVIDERS_NEWAPI_ENABLED:false}
            model: ${SPRING_OPEN_AI_MODEL_PROVIDERS_NEWAPI_MODEL:gpt-4.1}
            base-url: ${SPRING_OPEN_AI_MODEL_PROVIDERS_NEWAPI_BASE_URL:${NEWAPI_BASE_URL:http://127.0.0.1:3000/v1}}
            api-key: ${SPRING_OPEN_AI_MODEL_PROVIDERS_NEWAPI_API_KEY:${NEWAPI_API_KEY:}}
          local-account-pool:
            provider: account-pool
            enabled: ${SPRING_OPEN_AI_MODEL_PROVIDERS_LOCAL_ACCOUNT_POOL_ENABLED:false}
            model: ${SPRING_OPEN_AI_MODEL_PROVIDERS_LOCAL_ACCOUNT_POOL_MODEL:}
            base-url: ${SPRING_OPEN_AI_MODEL_PROVIDERS_LOCAL_ACCOUNT_POOL_BASE_URL:http://127.0.0.1:8000/v1}
            api-key: ${SPRING_OPEN_AI_MODEL_PROVIDERS_LOCAL_ACCOUNT_POOL_API_KEY:}

正式发布默认 Provider 指向 openai-compatible；simulated 默认启用，用于 Knowledge 等内部能力在模型不可用时降级兜底。真实外部上游仍需管理员通过环境变量、后台覆盖或 YAML 显式启用并配置 API Key。NewAPI 作为聚合上游时使用 provider: newapi，填写 NewAPI 实例 /v1 地址和平台颁发的令牌即可快速接入。

后台支持批量启停 Provider：

http

PUT /api/v1/admin/ai/platform/providers/status

json

{
  "providerNames": ["newapi", "openai"],
  "enabled": true
}

该接口只写入 Provider 数据库覆盖配置的启用状态，不修改 API Key、baseURL、模型、价格、路由或凭证池配置。结果会返回 updatedCount、unchangedCount、missingCount 和逐 Provider 处理明细，便于后台页面做批量启用 / 禁用反馈。

Provider 探测

后台 Provider 单点探测接口：

http

POST /api/v1/admin/ai/platform/providers/{providerName}/probe

该接口借鉴 NewAPI 渠道测试思路，但按后台路由和权限实现。探测会先读取目标 Provider 的模型列表，再发送一条极短 chat 请求测量真实响应耗时。请求体可以为空；需要指定模型时传入：

json

{
  "model": "gpt-4.1",
  "maxTokens": 8,
  "temperature": 0,
  "operations": ["chat", "embedding", "rerank", "image"],
  "operationProbeEnabled": true
}

返回结果包含：

success：短 chat 探测是否成功；如果启用 operation 探测，则已执行的 operation 探测失败也会让该值为 false。
durationMillis：探测耗时。
modelListSuccess、modelCandidateCount、modelCandidates：目标 Provider 模型列表读取情况。
operationProbes：按 operation 返回能力矩阵。chat 复用短 chat 探测结果；embedding 和 rerank 会在 operationProbeEnabled=true 时执行低成本真实探测；image、audio、file、batch、fine-tuning、assistant、vector-store、eval 等带副作用或成本更高的能力只做声明状态标记，不主动调用上游。
operationProbeCount、operationProbeSuccessCount、operationProbeFailureCount、operationProbeSkippedCount：operation 矩阵统计。successCount 只统计真实通过项，skippedCount 统计未执行项，未执行项不会让 Provider 总体失败。
errorType、status、upstreamCode、message、retryable：失败时的结构化错误摘要。

operations 为空时默认检查当前网关已知 operation；传入列表时只返回指定 operation。operationProbes[].status 可能为：

passed：已执行真实探测并通过。
failed：已执行真实探测但失败。
declared：Provider 声明支持，但该 operation 未做副作用探测。
unsupported：Provider 未声明支持该 operation。
skipped：本次请求关闭了额外 operation 探测。

后台 Provider 批量探测接口：

http

POST /api/v1/admin/ai/platform/providers/probe

请求体可以为空。为空时默认只探测已启用 Provider，并统计被跳过的未启用 Provider；需要指定范围时传入：

json

{
  "providerNames": ["newapi", "openai"],
  "enabledOnly": true,
  "maxTokens": 8,
  "temperature": 0,
  "operations": ["chat", "embedding", "rerank"],
  "operationProbeEnabled": true
}

批量结果包含：

providerCount：本次命中的 Provider 总数，包含跳过项。
probedProviderCount：实际发起探测的 Provider 数。
successCount、failureCount、skippedCount：成功、失败和跳过统计。
probes：逐 Provider 的单点探测结果。

批量探测按 Provider 顺序执行，避免一次操作对上游产生突发并发压力。单点和批量探测都不经过 AI Gateway，不写 ai_usage_event，也不触发 quota 预占 / 结算。由于探测会调用真实上游，生产环境应仅授予可信后台操作人员 ai:platform:update 权限。

Provider 模型同步

后台 Provider 模型目录同步接口：

http

POST /api/v1/admin/ai/platform/providers/{providerName}/models/sync

该接口会调用目标 Provider 的模型列表能力，将上游返回的模型写入 ai_model_catalog，用于快速建立本地模型目录、别名治理和后续价格 / quota 配置。请求体可以为空，默认启用新模型并默认开放：

json

{
  "modelEnabled": true,
  "openByDefault": true,
  "overrideExisting": false
}

字段含义：

modelEnabled：新增或覆盖模型目录时写入的启用状态。未传时，新增模型按上游启用状态或默认启用，已有模型保持原状态。
openByDefault：新增或覆盖模型目录时是否默认开放给网关用户。未传时，新增模型跟随启用状态，已有模型保持原状态。
overrideExisting：是否覆盖已存在模型目录。默认 false，保留后台人工维护的展示名、别名、fallback、备注和上下文配置；设置为 true 时会刷新展示名、能力标签、上下文窗口和最大输出 token 等上游技术元数据，但仍保留平台别名、fallback、备注以及未显式传入的启用 / 开放状态。

后台“同步模型”操作会先让管理员选择强制覆盖或增量同步：强制覆盖传入 overrideExisting=true，增量同步传入 overrideExisting=false。

能力标签来源优先级：

如果上游模型列表返回了模型级 capabilities，同步时以模型级能力为准。
如果上游模型没有返回能力标签，则使用当前 Provider 配置声明的 capabilities 作为目录兜底。
Provider 能力只做兜底，不覆盖已有模型级能力，避免把 Provider 总能力误套到单个模型。
对 NewAPI、OpenRouter 等聚合入口，OpenAI Compatible Provider 会额外识别模型列表中的 display_name / name、context_window / context_length、max_output_tokens / max_completion_tokens、architecture、top_provider、pricing、supported_parameters 和 per_request_limits。其中上下文窗口、最大输出和能力标签会进入模型目录字段，价格 / 架构 / 参数限制保留在 metadata 中，供后台运营二次配置和展示。

模型目录查询接口会基于最终 capabilities 同步返回 operation 能力画像：

supportedOperations：该模型可承接的网关 operation，例如 chat、stream、embedding、response。
filteredOperations：当前模型因能力标签不足会被网关过滤的 operation。
operationProfiles：逐 operation 展示 operation、requiredCapability 和 supported，便于后台页面绘制模型能力矩阵。

返回结果包含：

fetchedCount：上游返回模型总数。
createdCount、updatedCount、unchangedCount、skippedCount：新增、更新、保留和跳过统计。
items：逐模型处理结果，便于后台页面展示本次同步是否新增、覆盖或保留。
items[].capabilities、items[].supportedOperations、items[].filteredOperations、items[].operationProfiles：本次同步读取到的模型能力画像，便于同步后立即复核模型适合哪些网关 operation。
items[].contextWindow、items[].maxOutputTokens：本次同步读取到的上下文窗口和最大输出 token。
items[].metadata：本次同步读取到的可公开展示上游元数据，会过滤 api key、token、secret、password 等敏感键；价格、架构和参数限制这类信息优先用于后台展示和二次配置，不直接改变结算倍率。

模型同步属于后台运营动作，不经过 AI Gateway，不写 ai_usage_event，不触发 quota 预占 / 结算，也不修改 Provider API Key、baseURL、路由、价格或凭证池配置。

路由与优先级

Provider 和凭证优先级采用同一语义：priority 数值越大越优先。

路由候选按以下顺序计算：

启用状态优先。
priority 高的 Provider 优先。
同优先级内 weight 高的 Provider 优先。
默认 Provider 作为补充分。
名称稳定排序，保证观测和测试可复现。

spring-open-starter-ai-model 的 AiModelRouteSelector 会在未显式指定 Provider 时使用同一套优先级语义；同优先级组存在权重时，使用请求内容稳定哈希做分流。

后台路由保存接口只维护路由相关字段：启停、timeout、fallback、模型不可用降级、上游错误透传、priority、weight 和备注，不会清空 API Key、baseURL、默认模型或能力配置。

凭证池治理

凭证池用于同一个 Provider 配置实例下治理多组已授权 API Key、BYOK、服务凭证或兼容端点。Starter Provider 仍保持协议中立，只接收本次解析后的 baseUrl、apiKey 和 options。

核心类：

类	说明
`AiModelConfigResolverAdapter`	在本地配置之上叠加 Provider 覆盖和数据库凭证，并把选中凭证注入本次 Provider 配置
`AiPlatformProviderCredentialService`	后台凭证池 CRUD，负责 API Key 保护、脱敏响应和排序
`AiPlatformProviderCredentialCooldownService`	后台凭证人工冷却 / 解除冷却，负责写入 `manual_cooldown_until`
`AiPlatformProviderCredentialHealthOverviewService`	后台凭证健康概览，合并凭证配置、健康快照、冷却状态和调度可用性
`AiProviderCredentialHealthScoreCalculator`	计算 0-100 健康分
`AiProviderCredentialScheduler`	在最高优先级分层内按健康分与权重做加权随机调度
`AiProviderCredentialHealthService`	记录成功、失败、TTFT、连续失败、冷却和健康快照

支持策略：

策略	说明
`priority`	选择最高 `priority` 的启用凭证；同优先级按权重和名称稳定排序
`weighted`	先锁定最高 `priority` 分层，再在该层内按权重稳定哈希
`health-weighted`	先过滤冷却 / 低健康分凭证，再在最高 `priority` 分层内按 `weight * healthScore / 100` 加权随机

健康分默认维度：

维度	默认权重	来源
可用性	35%	最近窗口请求成功率
响应性能	25%	首 token 延迟 TTFT
稳定性	20%	限流和异常惩罚
生命周期	10%	首次观测后的 warmup 时长
状态	10%	人工 / 自动冷却状态

冷却规则默认按连续失败阶梯递增：

yaml

spring:
  open:
    ai:
      platform:
        credential-governance:
          enabled: true
          scheduler:
            enabled: true
            strategy: health-weighted
            min-score: 20
            degraded-fallback-enabled: false
          cooldown:
            consecutive-failure-threshold: 3
            levels:
              - failures: 3
                duration: 15m
              - failures: 6
                duration: 1h
              - failures: 10
                duration: 24h

AI Gateway 会在普通响应成功、流式结束片段成功、Provider 异常和流式写出失败时回写健康信号。选中凭证会写入响应 metadata 和 ai_usage_event，便于后续排障。

后台凭证健康概览接口：

http

GET /api/v1/admin/ai/platform/provider-credentials/health

该接口用于 NewAPI 风格渠道健康运维视角，只读合成 ai_provider_credential 和 ai_credential_health_snapshot，不解密 API Key，不调用上游模型，也不改变调度结果。返回内容包含：

字段	说明
`governanceEnabled` / `schedulerEnabled`	当前凭证治理和调度开关
`schedulerStrategy` / `schedulerMinScore`	当前调度策略和最低可调度健康分
`credentialCount` / `availableCredentialCount` / `coolingCredentialCount`	凭证总数、可调度数和冷却中数量
`averageHealthScore`	当前凭证平均健康分
`credentials[]`	每个凭证的 Provider、凭证名、启用状态、优先级、权重、健康分、有效权重、最高优先级分层、冷却状态、最近请求 / 成功 / 失败 / 限流 / 异常、TTFT、最近错误摘要

available=false 时，reason 会返回 disabled、cooling-down、score-too-low 或 scheduler-disabled，后台页面可直接用来提示运维原因。真实请求调度仍由 AiProviderCredentialScheduler 在调用链路内执行，健康概览只用于观测和排障。

后台凭证人工冷却接口：

http

PUT /api/v1/admin/ai/platform/providers/{providerName}/credentials/{credentialName}/cooldown

该接口用于 NewAPI 风格渠道人工摘除和恢复。它只写入或清除 ai_credential_health_snapshot.manual_cooldown_until，不禁用凭证、不修改 API Key、不清空自动冷却、不重置历史成功率或错误窗口。请求体必须在以下三种方式中三选一：

json

{
  "cooldownMinutes": 15
}

或：

json

{
  "manualCooldownUntil": "2026-06-08T14:30:00"
}

或：

json

{
  "clear": true
}

返回值为该凭证最新健康明细。人工冷却期间健康概览会显示 coolingDown=true、available=false、reason=cooling-down，调度器也会过滤该凭证；解除人工冷却后，凭证仍需满足启用状态、自动冷却状态和最低健康分，才会重新进入可调度候选。

模型目录与价格

模型目录来自 AiModelManager.models() 和 ai_model_catalog 数据库覆盖。平台默认保持上游官方模型名，平台别名只在 AI 网关入口解析，传给上游 Provider 的仍是官方模型名。

管理员可使用 POST /api/v1/admin/ai/platform/providers/{providerName}/models/sync 从单个 Provider 拉取上游模型列表并创建缺失的本地目录项。默认同步不会覆盖已有目录，避免误改人工维护的模型别名、fallback 和备注；需要刷新上游能力标签或上下文窗口时，再显式传入 overrideExisting=true。

模型目录 API 会同时返回 capabilities、supportedOperations、filteredOperations 和 operationProfiles。supportedOperations / filteredOperations 使用与运行时路由相同的 AiModelOperationCapabilities 映射规则，因此后台看到的模型能力矩阵和网关实际过滤行为保持一致；空能力标签的历史轻量模型只按兼容规则承接 chat / stream。

模型目录查询支持以下 query 参数，开放控制面和后台控制面共用同一套过滤规则：

keyword：模糊匹配 Provider、模型名、展示名、平台别名和能力标签。
providerName：按 Provider 配置实例名称精确过滤。
modelName：按官方模型名或平台别名精确过滤。
capability：按模型 capability 过滤，例如 chat、embedding、response。
operation：按网关 operation 过滤，例如 chat、stream、embedding、response、realtime。
operationSupported：与 operation 配合使用，默认 true 表示只看支持该 operation 的模型；传 false 可查看会被该 operation 过滤的模型。
enabled、openByDefault、databaseOverride：按启用状态、默认开放状态和数据库覆盖状态过滤。

价格目录来自 Provider metadata 和 ai_model_price 数据库覆盖。当前按每百万 token 维护平台售价和官方成本，返回平台收入、官方成本、毛利和毛利率基础字段。历史调用成本以 ai_usage_event 写入时的快照为准，不用当前价格回算历史。

Quota 计量

AI 模块采用 NewAPI 风格的 quota 倍率机制，但实现为框架内的 AiQuotaCalculator：

text

quota = (inputTokens + outputTokens * completionRatio) * modelRatio * groupRatio

若模型规则配置 fixedPriceQuota > 0，则单次调用直接使用固定 quota，不再按 token 公式计算。

后台运营接口由 AiPlatformQuotaRatioService 承接，Controller 只负责权限和响应封装。管理员可以维护：

分组倍率：PUT /api/v1/admin/ai/platform/quota/group-ratios/{groupCode}，groupCode 会归一为小写；设置 defaultGroup=true 时会取消其它分组的默认标记。
模型倍率：PUT /api/v1/admin/ai/platform/quota/model-ratios，按 providerName + modelName upsert；providerName="*" 表示模型通配规则；fixedPriceQuota=0 或空表示继续按 token 公式计费。

AI Gateway 的计费生命周期由 AiGatewayBillingService 承接。正式发布默认开启 spring.open.ai.gateway.billing.enabled=true 和 spring.open.ai.gateway.billing.reject-missing-account=true，网关会在调用上游前按模型倍率 / 分组倍率生成 quota 预占快照，并在 ai_usage_event 中记录实际用量、成本和毛利。如果应用提供 AiGatewayBillingAccountService 实现，网关会把预占、实际结算和失败释放委托给真实账户系统；如果没有接入该端口，网关会在调用上游前拒绝请求，避免产生无法扣费的真实模型成本。

平台质量评测接口 GET /api/v1/admin/ai/platform/quality 会返回默认开放模型的倍率配置覆盖数和缺口列表。未配置模型倍率时，quota 计算会继续按 1.000000 兜底；管理员对外提供网关服务前，应根据 missingModelRatioModels 补齐精确规则或 providerName="*" 通配规则。

同一接口也会返回上线就绪评分，后台「质量」页会展示 productionScore、productionLevel、productionReady、productionBlockers、productionRemediations 和 productionSignals。上线默认配置会启用鉴权、限流、计费和账户扣费适配；质量页负责把真实上游、Gateway Key、账户余额和 smoke 条件变成可观测阻断项，并把阻断项对应的处理位置、处理动作和排障说明直接返回给后台。

上线就绪检查包含：

production-secret-key：已配置专用 spring.open.ai.secret.encryption-key，长度不少于 32 位；等于应用共享密钥（含数据库播种行）仍视为未配置专用 key。
gateway-key-auth：已开启 spring.open.ai.gateway.key-auth.enabled=true，网关调用需要 Gateway Key。
gateway-rate-limit：已开启 spring.open.ai.gateway.rate-limit.enabled=true，并可按 Key、用户和 Provider 维度配置调用阈值。
billing-account-settlement：仅在 billing 已启用且 reject-missing-account=true 时检查；要求应用已提供 AiGatewayBillingAccountService 真实账户扣费端口。
real-provider-smoke-target：至少存在一个已启用、非本地模拟 Provider，并且 API Key 已配置。
gateway-key-coverage：至少存在一个启用的 Gateway Key。
real-traffic-smoke：已产生真实用量事件，确认模型列表、普通 chat、stream 和 Key 鉴权 smoke 至少跑通过一次。
billing-decision：正式发布默认开启 gateway.billing.enabled=true、gateway.billing.reject-missing-account=true 和 Money 扣费适配；管理员需要准备 Gateway Key 归属用户的 AI token 余额账户。

上线检测运行记录

后台「质量」页提供主动上线检测按钮，对当前启用 Provider 执行一次低成本检测并把结果写入 ai_platform_check_run。检测逻辑只在管理员主动点击或调用接口时执行，不在 /api/v1/ai/gateway/** 模型请求链路中增加额外阻断或实时检查，因此不会影响网关调用性能。

运行接口：

http

POST /api/v1/admin/ai/platform/production-checks/run

默认请求体可以为空；也可以指定 Provider、模型或开启更深的 operation 探测：

json

{
  "providerNames": ["newapi", "openai"],
  "model": "gpt-4.1",
  "maxTokens": 8,
  "operationProbeEnabled": false,
  "enabledOnly": true
}

检测内容包括：

读取 AiPlatformQualityService 的上线就绪评分和阻断项。
执行 AiPlatformProviderProbeService 批量 Provider 探测，默认只做低成本模型列表和短 chat smoke。
汇总 AiPlatformGatewaySmokeService 的 Gateway smoke 画像，检查网关开关、Key 鉴权、网关限流、启用 Key、模型发现、最近带 Key 用量、chat smoke 和 stream smoke 证据。
捕获质量评分或 Provider 探测运行时异常，并保存为 production-check-runtime 阻断项，便于管理员排查检测任务自身失败。
保存 summary、detailJson、blockerRemediations、Provider 成功 / 失败 / 跳过统计、失败 Provider 摘要和执行耗时。

Gateway smoke 画像不会主动发起新的模型调用，也不会消耗 token。它只读取当前 Gateway Key、模型目录和最近 24 小时 ai_usage_event，并复用网关状态接口中的生产开关信号，把“是否已按生产方式跑过模型发现、chat、stream、Key 鉴权和用量落库”整理进 detailJson.gatewaySmoke。如果缺少证据，missingSteps 会返回：

gateway-enabled
gateway-key-auth
gateway-rate-limit
gateway-key-ready
model-discovery
gateway-key-usage
chat-smoke
stream-smoke

如果需要生成真实调用证据，后台「质量」页提供“运行真实 Smoke”按钮，也可以直接调用：

http

POST /api/v1/admin/ai/platform/gateway-smoke/run

默认请求体可以为空；也可以指定 Gateway Key、模型、提示词和是否运行 Stream：

json

{
  "gatewayKeyId": 1,
  "model": "gpt-4.1",
  "prompt": "Reply with OK.",
  "maxTokens": 8,
  "temperature": 0,
  "streamEnabled": true
}

该运行器会选择启用状态、包含 ai:gateway:chat:write scope 的 Gateway Key，并选择一个开放模型；指定 gatewayKeyId 或 model 时会优先使用指定值。运行时会临时注入 Gateway Key / OpenAPI grant 上下文，走真实 AiGatewayProtocolService.chatCompletions(...) 链路，因此会复用网关鉴权上下文、Provider 路由、限流、quota、usage event、Provider / Credential 健康和流式计量。它只在管理员主动点击或调用接口时运行，不会在普通 /api/v1/ai/gateway/** 请求中增加额外检查。

响应会返回：

operations：chat-smoke、stream-smoke 等步骤的成功状态、HTTP 状态码、耗时和消息预览。
gatewaySmoke：运行完成后重新读取的 Gateway smoke 画像，用于确认最新真实用量证据是否已经写入。
success：所有执行步骤是否通过。

检测结果为 failed 或 warning 时，服务会发布 AiGatewayAlertEvent：

type=ai.production-check-failed
provider=production-check
model=readiness
scopeCode=ai:platform:update
path=/api/v1/admin/ai/platform/production-checks/run
attributes 包含 checkRunId、checkRunKey、checkStatus、qualityScore、productionScore、productionReady、blockerCodes、Provider 探测统计、失败 Provider 摘要、Gateway smoke 摘要和 durationMs

事件发布器会隔离监听器异常，不影响检测结果落库。后续 Notification、Webhook、审计或运维中心只需要监听 AiGatewayAlertEvent，按 type=ai.production-check-failed 过滤即可消费上线检测失败 / 降级告警；检测通过时不会发布该告警，避免正常巡检产生噪声。

AI 模块默认接入统一 Notification 规则链路，内置规则模板编码为：

ai.balance-low
ai.package-exhausted
ai.key-exception
ai.provider-failure
ai.rate-limited
ai.production-check-failed

监听器默认规则不内置接收人。生产环境应在后台通知规则中为上述 ai.* 规则配置运维或管理员接收人，并按需要启用站内信、邮件或 Webhook 通道。告警通知的 variables 与 attributes 会携带 provider、model、traceId、eventKey、reason、errorType、errorCode、errorMessage 以及对应告警的扩展字段；通知跳转目标统一指向后台 AI 运营页 /ai/platform。

分页查询接口：

http

GET /api/v1/admin/ai/platform/production-checks?page=1&size=10

最近一次检测摘要接口：

http

GET /api/v1/admin/ai/platform/production-checks/latest

检测详情接口：

http

GET /api/v1/admin/ai/platform/production-checks/{checkRunId}

分页和最近一次摘要接口默认不返回 detailJson，避免后台质量页加载历史记录时带出过大的探测明细；但会返回 blockerCodes 和 blockerRemediations，便于列表直接展示治理建议。需要排障时，后台详情抽屉或详情接口会按单条记录读取完整 detailJson，其中包含质量评分快照、Provider 批量探测明细、Gateway smoke 画像和运行时异常摘要。后台详情抽屉会把 detailJson.gatewaySmoke 结构化展示为“网关试运行”，直接显示整体状态、缺失步骤、平台 / 网关、限流 / 计费、Realtime / 健康聚合、启用 Key、模型发现、带 Key 用量以及最近 chat / stream 调用证据；完整 JSON 仍保留用于深度排障。

后台页面会展示最近检测状态、生产评分、Provider 探测统计、阻断项治理建议、失败摘要和耗时；点击详情可查看完整 JSON。准备对外提供 AI 网关服务前，建议管理员先完成：

配置专用 SPRING_OPEN_AI_SECRET_ENCRYPTION_KEY。
开启 spring.open.ai.gateway.key-auth.enabled=true。
保持 spring.open.ai.gateway.rate-limit.enabled=true，并按上线容量调整 key-per-minute、user-per-minute、provider-per-minute 等阈值。
配置至少一个真实 Provider 或 NewAPI 聚合上游，并确认 API Key 已可用。
创建启用状态的 AI Gateway Key。
在后台质量页运行真实 Gateway smoke，确认 Chat / Stream 步骤通过并生成 usage event 证据。
在后台质量页运行上线检测，确认结果通过或逐项处理阻断项。
收费运营前再开启 billing，接入 AiGatewayBillingAccountService，再复验 quota、账单、用量事件和成本毛利。

表	说明
`ai_group_ratio`	分组倍率；默认 seed 写入 `default = 1`
`ai_model_ratio`	Provider + 模型维度倍率，支持 `provider_name='*'` 通配
`ai_usage_event`	固化 `quotaGroupCode`、`quotaModelRatio`、`quotaCompletionRatio`、`quotaGroupRatio` 和 `quotaCount`

用量汇总

后台用量汇总接口：

http

GET /api/v1/admin/ai/platform/usage/summary

该接口用于 NewAPI 风格运营看板，读取 ai_usage_event 快照并按相同筛选条件聚合，不重新计算历史价格、成本或 quota。常用筛选参数和用量明细一致：

参数	说明
`keyword`	在事件键、应用 Key、Provider、模型、实际 Provider、凭证名、结果码和 traceId 中模糊搜索
`providerName` / `modelName`	精确筛选 Provider 和模型
`resultCode`	精确筛选调用结果码
`appKey`	精确筛选调用来源应用 Key 或 Gateway Key 上下文
`traceId`	精确定位单次调用链路
`upstreamCredentialName`	精确筛选上游凭证
`billable` / `stream`	筛选可计费事件和流式事件
`startedAt` / `endedAt`	按 `occurredAt` 时间区间筛选

返回字段包含事件总数、可计费事件数、流式事件数、fallback 事件数、输入 / 输出 / 总 token、可计费 token、quota 消耗、平台收入、官方成本、毛利、毛利率、平均耗时、首次 / 最近发生时间，并提供按币种、Provider、模型、结果码和日期的聚合列表。该接口只读，不经过 AI Gateway，不触发 quota 预占 / 结算，也不保存 prompt / completion 全文。

Gateway Key 用量汇总

后台 Gateway Key 用量汇总接口：

http

GET /api/v1/admin/ai/platform/gateway-keys/usage/summary

该接口用于 NewAPI 风格的 Key 用量排行和额度治理，读取 ai_gateway_key 与 ai_usage_event 快照，按 ai_usage_event.app_secret_id = ai_gateway_key.id 聚合调用事件。它不重新计算历史价格、成本或 quota，也不触发 Key 鉴权、quota 预占或结算。

Key 维度筛选参数：

参数	说明
`keyId`	精确筛选 Gateway Key ID
`keyName`	按 Key 名称模糊搜索
`enabled`	筛选启用或停用 Key
`ownerUserId`	筛选归属用户
`groupCode`	筛选 quota 分组
`includeUnusedKeys`	是否返回当前筛选范围内无调用事件的 Key
`limit`	返回排行数量，默认 100，最大 500

用量事件筛选参数与全局用量汇总一致，包括 keyword、providerName、modelName、resultCode、appKey、traceId、upstreamCredentialName、billable、stream、startedAt 和 endedAt。

返回字段包含：

总览：Key 数、启用 Key 数、发生调用的 Key 数、未匹配到有效 Key 的事件数。
用量：事件数、可计费事件数、流式事件数、fallback 事件数、输入 / 输出 / 总 token、可计费 token、quota 消耗、平台收入、官方成本、毛利、毛利率和平均耗时。
Key 明细：Key ID、名称、脱敏 Key、归属主体、分组、累计 quotaUsed、quotaLimit、剩余额度、使用率、是否不限量、Key 级限流策略、最近使用时间、最近 IP 和 User-Agent。

quotaLimit=0 表示不限量，此时 quotaRemaining=null，quotaUnlimited=true。按时间区间筛选时，明细里的 quotaCount 是该时间区间内从 ai_usage_event 聚合出的消耗，quotaUsed 是 Key 表里的累计已用额度，两者用于不同运营场景。

Gateway Key 限流策略

后台创建或更新 Gateway Key 时，可以在 POST /api/v1/admin/ai/platform/gateway-keys 和 PUT /api/v1/admin/ai/platform/gateway-keys/{keyId} 请求体中配置 Key 级限流：

json

{
  "keyName": "developer-key",
  "rateLimitPerMinute": 60,
  "rateLimitPerDay": 5000,
  "maxConcurrent": 2
}

字段	说明
`rateLimitPerMinute`	当前 Key 每分钟调用次数上限；空表示使用 `spring.open.ai.gateway.rate-limit.key-per-minute` 全局默认，`0` 表示 Key 维度不限
`rateLimitPerDay`	当前 Key 每日调用次数上限；空表示使用 `spring.open.ai.gateway.rate-limit.key-per-day` 全局默认，`0` 表示 Key 维度不限
`maxConcurrent`	当前 Key 最大并发调用数；空表示使用 `spring.open.ai.gateway.rate-limit.key-max-concurrent` 全局默认，`0` 表示 Key 维度不限

Key 级限流只覆盖 Key 这一维度，不会关闭 App、User 或 Provider 维度的全局限流。调用链路在 AiGatewayKeyAccessFilter 解析 Key 后，把限流策略写入 AiGatewayUsageContext，再由 AiGatewayRateLimitService 在模型调用前执行检查和并发许可持有。该能力用于 NewAPI 风格的单 Key 风控、试用 Key 限额、团队 Key 分层和运营临时放量。

Gateway Key 批量启停

后台 Gateway Key 批量启停接口：

http

PUT /api/v1/admin/ai/platform/gateway-keys/status

该接口用于 NewAPI 风格的 Key 批量封禁、恢复访问和应急风控。它只更新 ai_gateway_key.key_enabled，不轮换 Key、不清空 quota、不删除白名单、scope、模型或 Provider 限制，也不重算历史用量事件。

请求体：

json

{
  "keyIds": [1, 2, 3],
  "enabled": false
}

返回结果会按去重后的 Key ID 顺序给出逐项明细：

字段	说明
`keyCount`	去重后的请求 Key 总数
`updatedCount`	状态发生变化并已更新的 Key 数
`unchangedCount`	已存在但状态与目标状态一致的 Key 数
`missingCount`	未找到或已删除的 Key 数
`items[].changed`	当前 Key 是否产生启停状态变更

禁用后的 Key 无法通过 AiGatewayKeyAccessFilter 鉴权，但历史 ai_usage_event 和已累计 quotaUsed 保留，便于后续用量追踪、账务对账和恢复访问。

Gateway Key quota 运维

后台 Gateway Key quota 运维接口：

http

PUT /api/v1/admin/ai/platform/gateway-keys/{keyId}/quota

该接口用于 NewAPI 风格的 Key 额度修正、运营补偿和测试环境复位，只更新 ai_gateway_key.quota_used，不修改 quotaLimit，不写 ai_usage_event，也不重新计算历史成本或账单。请求体必须在 quotaUsed 和 quotaDelta 中二选一：

json

{
  "quotaUsed": 0
}

或：

json

{
  "quotaDelta": -100
}

参数说明：

参数	说明
`quotaUsed`	直接把 Key 已用 quota 设置为指定非负值，常用于清零、复位或人工校正
`quotaDelta`	在当前已用 quota 上增减，负数表示回退额度；结果小于 0 时会归零

接口返回更新后的 AiGatewayKeyVO，其中 quotaUsed 为最新累计已用额度。真实调用链路仍由 AiGatewayBillingService 和 AiGatewayKeyService.recordQuotaUsage 在调用成功后自动累计 quota；该运维接口只服务人工修正，不代表历史调用事件被删除或重算。

用量明细

后台用量事件明细接口：

http

GET /api/v1/admin/ai/platform/usage/events

该接口用于 NewAPI 风格的调用日志和用量审计，读取 ai_usage_event 快照，不重新计算历史价格或 quota。常用筛选参数：

参数	说明
`page` / `size`	分页参数，`size` 最大 500
`keyword`	在事件键、应用 Key、Provider、模型、实际 Provider、凭证名、结果码和 traceId 中模糊搜索
`providerName` / `modelName`	精确筛选 Provider 和模型
`resultCode`	精确筛选调用结果码
`appKey`	精确筛选调用来源应用 Key 或 Gateway Key 上下文
`traceId`	精确定位单次调用链路
`upstreamCredentialName`	精确筛选上游凭证
`billable` / `stream`	筛选可计费事件和流式事件
`startedAt` / `endedAt`	按 `occurredAt` 时间区间筛选

返回字段包含 Provider、模型、fallback、路由策略、候选 Provider、上游凭证、输入 / 输出 / 总 token、quota 分组和倍率、平台收入、官方成本、毛利、耗时、traceId 和发生时间。该接口只读，不经过 AI Gateway，不触发 quota 预占 / 结算，也不保存 prompt / completion 全文。

AI 网关 quota 预占和结算按正式发布默认开启：

yaml

spring:
  open:
    ai:
      gateway:
        billing:
          enabled: true
          default-group-code: default
          reject-missing-account: true
          money:
            enabled: true
            asset-code: points:AI_TOKEN
            decimals: 6
            auto-create-account: true

Money 适配器会按 Gateway Key 的归属用户找到或创建 asset-code 对应余额账户：调用上游前冻结预估 quota，成功后释放冻结并按实际 usage 消费，失败时释放冻结。所有流水使用 ai_usage_event 派生的幂等键，避免重试或补偿时重复扣费。

完整生产配置示例：

yaml

spring:
  open:
    ai:
      gateway:
        billing:
          enabled: true
          reject-missing-account: true
          money:
            enabled: true
            asset-code: points:AI_TOKEN
            decimals: 6
            auto-create-account: true

网关调用链

普通响应调用链：

text

AiGatewayApiController
  -> AiGatewayProtocolService
  -> AiPlatformModelService.resolveRequest
  -> AiGatewayRateLimitService
  -> AiGatewayBillingService.reserve
  -> AiModelManager.chat
  -> AiGatewayBillingService.settle
  -> AiGatewayUsageMeteringService.recordSuccess
  -> AiGatewayProviderHealthService / AiProviderCredentialHealthService

流式响应会复用同一套模型解析、限流、预占和健康回写，在 SSE 结束片段或写出失败时完成结算、释放和失败记录。

网关协议字面量集中在 AiGatewayProtocolConstants，SSE 响应写出集中在 AiGatewayStreamResponseFactory，Controller 不写业务逻辑。

安全与审计

Provider API Key 和凭证池 API Key 只以密文落库。
控制面响应只返回 apiKeyConfigured，不返回明文或密文。
公开 metadata 会过滤 secret、password、token、api-key、private-key、access-key 等敏感 key。
用量事件固化 Provider、模型、fallback、路由策略、候选 Provider、凭证、token、quota、traceId 和耗时。
默认不保存完整 Prompt / Completion；需要保存时必须另行设计脱敏、授权和关闭能力。
后台写操作检查 ai:platform:update，读操作检查 ai:platform:view。

验证

AI 模块改动后至少执行：

bash

./mvnw -pl spring-open-modules/spring-open-module-ai -am test -DskipITs -DskipFrontend -Dsurefire.failIfNoSpecifiedTests=false

如果触碰 AI Model starter，还需要执行：

bash

./mvnw -pl spring-open-starters/spring-open-starter-ai-model -am test -DskipITs -DskipFrontend -Dsurefire.failIfNoSpecifiedTests=false

如果触碰 AI Skill starter，还需要执行：

bash

./mvnw -pl spring-open-starters/spring-open-starter-ai-skill -am test -DskipITs -DskipFrontend -Dsurefire.failIfNoSpecifiedTests=false

如果触碰迁移文件，还需要执行：

bash

./.ai/scripts/check migrations

AI 模型平台 ​

定位 ​

模块边界 ​

API 路由 ​

数据模型 ​

Provider 配置 ​

Provider 探测 ​

Provider 模型同步 ​

路由与优先级 ​

凭证池治理 ​

模型目录与价格 ​

Quota 计量 ​

上线检测运行记录 ​

用量汇总 ​

Gateway Key 用量汇总 ​

Gateway Key 限流策略 ​

Gateway Key 批量启停 ​

Gateway Key quota 运维 ​

用量明细 ​

网关调用链 ​

安全与审计 ​

验证 ​

AI 模型平台

定位

模块边界

API 路由

数据模型

Provider 配置

Provider 探测

Provider 模型同步

路由与优先级

凭证池治理

模型目录与价格

Quota 计量

上线检测运行记录

用量汇总

Gateway Key 用量汇总

Gateway Key 限流策略

Gateway Key 批量启停

Gateway Key quota 运维

用量明细

网关调用链

安全与审计

验证