AI 总览
受众：开发者 摘要：AI 能力入口：AI 模型供应商平台、AI 模型网关、AI 模型调用底座、AI Skill、AI 任务和 AI Agent 接入。
框架的 AI 能力分为两层：
- 框架底座：提供 AI 模型调用、AI Skill 声明、任务编排、Provider 扩展、OpenAPI 元数据和 Agent 接入约定。
- 业务平台：承载 AI 模型供应商平台、AI 模型网关、Token 计量计费、用户 API Key、供应商路由和运营控制台。
当前阶段已经启动独立 spring-open-module-ai，用于承接 AI 模型平台、网关、Provider、模型目录、计量、AI Skill 和运营能力；AI 能力不再挂在 spring-open-module-open-platform 下。spring-open-starter-ai-model 已内置 mock / log / simulated / account-pool / openai-compatible / newapi / spring-ai Provider。spring-open-starter-ai-skill 提供 SKILL.md 发现、解析、激活匹配和安全资源访问策略，AI 模块负责数据库态 Skill 导入、版本、启停和运行日志。DeepSeek 作为第一阶段正式供应商，推荐以 deepseek 配置实例复用 openai-compatible 公共底座；NewAPI 可直接通过 provider: newapi 作为聚合上游快速接入；simulated Provider 用于低成本联调 chat / stream / usage / fallback / 审计链路，不访问外部模型服务；spring-ai Provider 基于 Spring AI 2.0.0 最小接入，默认关闭，适合验证 Spring AI 生态能力。AI 网关当前已开放 OpenAI Compatible /models / /v1/models、普通 / 流式 chat/completions、Claude /claude/v1/models / 普通与流式 /claude/v1/messages、Codex /codex/v1/models / 普通与流式 /codex/v1/responses；平台控制面已具备 Provider、模型、价格目录、成本毛利、套餐、Skill 管理和路由策略入口，用户控制台已具备 AI Gateway Key、用量汇总和调用明细第一阶段 contract。PC 用户端 /ai 与 App H5 /ai/index 已提供类 ChatGPT 的前台对话入口，复用当前登录用户的 AI Gateway Key、模型目录、余额 / 套餐额度、预算和用量事件链路；管理型 Key、预算、市场启用和调用明细仍在 PC /account/ai 与 App 同页控制台区域维护。
后台 AI 平台 下的 AI 模型网关运营监控大屏用于平台运维观察 Provider、模型目录、Gateway Key、用量、Token、Quota、成本、毛利、质量、凭证健康和对账风险。大屏图表直接读取 AI 平台现有汇总、Key 用量、最近调用事件、Provider 凭证健康、质量和对账接口，不使用前端模拟趋势数据，并支持定时静默刷新。
后台 AI 平台 > AI 模型商家 同时提供商家运营概览。页面顶部会读取 GET /api/v1/admin/ai/merchants/operations/overview，展示近 30 天商家总数、LIVE 商家数、活跃商家数、调用台账、商家应收、平台佣金、成功率、平均延迟、待结算和冻结结算；商家排行会按收入、成功率、流量和治理状态输出 Top 商家，并给出成功率低、延迟高、商家停用、结算冻结等治理提示。该入口只做只读运营观察，不改变网关路由、模型市场排序或结算状态。
同一页面可在商家行操作中维护“治理策略”。策略默认关闭，不影响商家模型调用；启用后可配置每日 quota 上限、允许 / 拒绝用户 ID、允许 / 拒绝 Gateway Key ID、允许 / 拒绝能力列表。网关在第三方商家模型调用预占前执行该策略，命中黑名单、未命中白名单或日 quota 不足时直接拒绝，不发起上游调用；quota 采用 reserve / settle / release 语义，上游失败会释放预占，成功后按真实 usage 修正额度。
后台 AI 平台 > AI 模型市场 用于运营第三方商家模型的市场展示策略。平台运营可以查看全部第三方商家模型，维护排序分、置顶、隐藏、人工干预原因和试用策略（免费次数、折扣比例、平台补贴、有效期），也可以按凭证健康、近 30 天调用成功率 / 延迟、价格配置和发布状态刷新质量排序分。质量刷新会自动隐藏缺价、不可路由、凭证健康极低或已有调用样本但成功率 / 延迟异常的自动托管模型，并在结果里返回自动隐藏数量和治理动作；人工置顶、人工隐藏和人工原因继续保留。页面还会按同一基础模型聚合多个商家候选，结合市场排序、近 30 天成功率 / 延迟和价格给出优选推荐，帮助运营判断更合适的商家模型；推荐不会自动替换用户已启用模型。网关模型发现接口会按当前 Gateway Key、OpenAI-Project 和用户上下文返回“平台自营模型 + 已启用商家模型 + 默认推荐商家模型”，默认推荐数量由 spring.open.ai.gateway.recommended-merchant-model-count 控制，完整应用默认 10 个，模块与配置 schema 默认 0 个，后台可按运营需要调大，0 表示关闭默认推荐。默认推荐只从已 LIVE、已发布、未隐藏的商家模型中按置顶 / 排序分补充，作为付费模型可直接调用；用户显式停用的同名商家模型不会被默认推荐重新打开。用户可通过控制台 API 选择账号全局、OpenAI-Project 项目或指定 AI Gateway Key 启用某个商家模型，并显式选择付费或试用模式；PC / App 当前已提供账号全局、OpenAI-Project 项目与 Key 级选择器，以及试用转付费动作。
入口导航
| 文档 | 说明 |
|---|---|
| AI 模型平台 | spring-open-module-ai 的平台控制面，负责供应商、模型、价格、用户 AI Gateway Key、用量和成本 / 毛利运营 |
| AI 模型网关 | 调用面为 /api/v1/ai/gateway/**，承载 OpenAI Compatible、Claude / Anthropic Messages、Codex / Responses API 兼容入口 |
| AI 模型 | spring-open-starter-ai-model，统一 AI 模型调用 Facade / Manager / ConfigResolver / Provider SPI |
| AI Skill | spring-open-starter-ai-skill 和 AI 模块 Skill 控制面，负责 SKILL.md 解析、激活、版本、启停和运行日志 |
| AI 任务 | spring-open-starter-ai-task，组织 AI 任务处理器、同步执行和后续队列 / 调度 / 管道衔接 |
| AI Agent 接入 | OpenAPI 元数据、Open Platform 调用、工具调用约定和第三方服务端接入样板 |
模块关系
AI Agent / SDK / 用户应用
↓
AI 模型网关 /api/v1/ai/gateway/**
↓
AI 模型平台控制面 /api/v1/admin/ai/platform/**
├── spring-open-starter-ai-model
│ ↓
│ AiModelProvider(openai-compatible / newapi / log / mock / simulated / account-pool ...)
└── spring-open-starter-ai-skill
↓
SkillRegistry / SKILL.md / 运行日志spring-open-module-ai 是 AI 业务模块，内部按 platform、gateway、provider、model、apikey、skill、usage、billing、risk 等子域演进；spring-open-starter-ai-model 是通用模型调用底座，不放运营后台、余额、计费和用户控制台逻辑；spring-open-starter-ai-skill 是 Skill 文档解析与激活底座，不直接执行脚本或业务工具。
B2B2C 模型商城：请求路由与资金流转
AI 网关在 B2B2C 模式下聚合「平台自营模型」和「第三方商家模型」：用户只用一套平台地址 + 一个密钥调用，网关按 model 字段路由，储值钱包统一扣费，平台按调用向商家分账。设计依据见 ADR-064~067。
要点：
- 命名与路由（ADR-065）：平台自营用官方名、无后缀；第三方用
baseModel@merchantCode。按最后一个@解析；merchantCode不含@。命中商家时校验商家已审核通过、模型属于该商家且已发布——不存在 / 未通过 / 已停用一律拒绝，绝不 fallback 到自营或其他商家（ADR-064 隔离红线）。 - 前台对话入口：PC
/ai是用户直接使用 AI 的主入口，App H5/ai/index提供移动端对话卡片；两端通过POST /api/v1/ai/console/chat/completions调用登录态控制台代理。该代理会优先使用用户选择的 AI Gateway Key，未指定时使用当前账号第一个启用 Key；账号没有 Key 时自动创建一个只面向控制台对话的默认 Key。接口只返回普通 JSON，不承担外部 SDK 协议，成功时把 OpenAI Compatible 响应放在Result.data，并复用网关已有模型启用、余额 / 套餐扣费、预算限额、Provider 路由和 usage event 计量；余额不足、预算超限、模型未启用或上游失败时按现有网关错误语义阻断或释放预占。 - 模型市场、默认推荐与启用清单：OpenAI
/models//v1/models、Codex/codex/v1/models、Claude/claude/v1/models和 Gemini/gemini/v1beta/models都按当前 Gateway Key、OpenAI-Project和用户上下文返回“平台自营模型 + 已启用商家模型 + 默认推荐商家模型”。默认推荐由spring.open.ai.gateway.recommended-merchant-model-count控制，按市场置顶 / 排序分从可路由第三方模型中补充；完整应用默认 10 个，模块与配置 schema 默认 0 个，管理员可在后台配置中心改成 100 等更高数量，质量排序分仍能在未手工置顶时提供稳定推荐。启用接口支持三种范围：不传gatewayKeyId/projectId时是用户级全局启用；传入projectId时按调用方OpenAI-Project请求头隔离；传入gatewayKeyId时只对该 AI Gateway Key 生效且优先级最高。启用时可传billingMode=PAID|TRIAL，默认PAID；TRIAL只在后台试用策略有效、免费次数或折扣额度可用时生效。网关调用第三方模型时按“当前 Key 级绑定 → 当前 Project 级绑定 → 用户级绑定 → 默认推荐”顺序校验，既不在显式启用清单也不在默认推荐清单时返回model_not_enabled，不发起上游调用；默认推荐按付费模型处理，用户显式停用后不会被默认推荐重新开启。上游调用前试用额度不可用或耗尽时返回trial_not_available，必须由用户显式转为付费绑定后再调用。若试用请求已在 reserve 阶段通过、但上游返回后 settle 阶段因并发耗尽或策略窗口失效而不可再按试用结算，默认会按付费全价完成结算并在ai_merchant_ledger.trial_fallback=true留痕；这不是无痕静默转付费，运营和客服可按台账追溯并复用既有冲正。PC / App 控制台当前已提供账号全局、OpenAI-Project 项目与指定 AI Gateway Key 选择器，以及试用 / 付费启用和试用转付费动作。处于DEPRECATED退市兼容窗口的商家模型会在模型市场返回deprecated、deprecationWarning和replacementModels，PC / App 展示退市提示和替代建议；替代模型必须由用户显式启用或进入默认推荐，平台不会自动替换已指定的模型名。 - 预算限额策略：用户控制台
GET /api/v1/ai/console/budget-policies可查询当前账号的账号级与项目级预算，PUT /api/v1/ai/console/budget-policies/user保存账号全局预算，PUT /api/v1/ai/console/budget-policies/projects/{projectId}保存OpenAI-Project项目预算。后台AI 平台 > 额度倍率可维护组织级预算，接口为GET /api/v1/admin/ai/platform/budget-policies与PUT /api/v1/admin/ai/platform/budget-policies/organizations/{organizationId}。网关在自营和第三方商家模型调用前按预估 quota 对账号 / 项目 / 组织预算做原子预占，超限返回预算超限错误且不发起上游；account / merchant 预占失败或上游失败会释放预算，调用成功后按实际 quota 修正预占差额。PC/account/ai与 App H5/ai/index已提供账号全局 / 项目预算查看和保存入口；Key 级额度仍由 AI Gateway Key 的 quota 配置承担。 - 后台市场运营：后台
AI 平台 > AI 模型市场可维护第三方模型的展示排序、置顶、隐藏和试用策略；后台可看到沙箱 / 隐藏等运营态模型，用户侧市场仍只展示 LIVE / APPROVED / 未隐藏模型。质量评分刷新会综合凭证健康、近 30 天成功率 / 延迟、价格配置和发布状态写回市场排序分，并自动隐藏缺价、不可路由、凭证健康极低或已有调用样本但成功率 / 延迟异常的自动托管模型；刷新结果会返回autoHiddenCount和每个模型的治理动作，人工置顶 / 隐藏 / 原因不会被覆盖。同模型商家优选推荐会在同一基础模型存在多个可路由商家候选时输出推荐模型和评分因子，评分只用于市场运营与显式启用决策，不会让网关自动切换商家。试用策略命中后会在ai_merchant_ledger记录是否免费调用、折扣比例、用户减免金额、平台补贴商家金额和补贴口径，方便用户账单、商家应收与平台对账复算；付费绑定不会套用试用策略。试用免费次数按当前绑定作用域独立统计：用户级、OpenAI-Project项目级和 AI Gateway Key 级互不占用额度，并在台账中快照trial_scope、trial_project_id或trial_gateway_key_id。试用请求在 settle 阶段竞态失效时会按付费全价落账并标记trial_fallback，不计入免费次数，后续退款 / 客服补偿复用AiUsageAdjustmentService。 - 商家运营概览：后台
AI 平台 > AI 模型商家通过只读概览接口展示商家状态、近 30 天收入 / 佣金 / 试用减免、成功率、延迟、待结算 / 冻结结算、Top 商家排行和治理信号。它帮助运营判断哪些商家需要降权、冻结、限流或复核，但不会自动替换用户已启用模型，也不会修改结算状态。 - 商家访问治理：后台可为单个商家启用治理策略，配置日 quota 上限、用户 / Gateway Key 黑白名单和能力黑白名单。策略在网关商家模型预占前执行，拒绝时不调用上游、不扣钱包、不生成商家台账；没有策略或策略关闭时默认放行，避免生产接入初期因缺配置跑不通。
- 商家工作台：后台
AI 平台 > AI 模型商家可把商家绑定到 IAM 用户 ID 作为主账号；商家主账号或成员可在 PC 账号中心/account/ai-merchant按角色维护渠道密钥、模型上架、发布状态和成员权限，并查看应收台账与结算记录。主账号隐式为OWNER，成员支持ADMIN/OPERATOR/FINANCE/VIEWER与启停状态；OWNER/ADMIN可维护渠道、模型和成员，OPERATOR只维护渠道与模型，FINANCE只查看账务，VIEWER全只读。商家结算净额直接入账主账号拥有的 Money 用户余额账户，银行卡 / 钱包等提现目的地由 Money 提现流程维护；工作台不再提供独立结算账户维护入口。接口前缀为/api/v1/ai/merchant-console/**，后端按当前用户解析商家身份并只返回当前商家的数据。应收台账支持按关键词、发布模型、用户 ID、试用命中和发生时间筛选，并展示请求号、usageEvent、用户扣费、平台佣金、商家应收、试用补贴快照和试用降级标记，方便商家侧账务审计。 - 后台结算运营：后台
AI 平台 > AI 商家结算支持生成 / 重算周期结算单、对账通过、合规放行、请求余额入账、登记入账完成引用、登记失败、冻结和解冻；同一商家 / 周期结算单按唯一键幂等，管理员重复点击或多节点同时生成时只会返回同一张结算单，不重复生成。默认开启超时自动放行：生成 / 重算后先投递 Queue 延迟任务到ai-merchant-settlement专用队列，正常情况下到期即复用 readiness 检查并入账；Scheduler 固定延迟任务只做兜底扫描，处理队列不可用、消息漏投或异常断链。净应付大于 0、币种存在、商家已绑定主账号且money-balanceProvider 可用时自动进入PAYABLE并入账商家主账号余额，成功后标记PAID。异常才进入人工复审：净额异常、币种缺失、商家主账号缺失、端口缺失或自动入账异常时，结算单会按配置冻结为FROZEN并在备注保留阻断码。生成结算单时会快照周期内唯一币种，台账和冲正混入多币种会拒绝生成，避免一张结算单跨币种入账。后台可用GET /api/v1/admin/ai/settlements/payout-providers查看当前装配的余额入账 Provider；当前 AI 模块内置 Provider 仅为money-balance。手工请求入账前会先读取GET /api/v1/admin/ai/settlements/{settlementId}/payout-readiness，统一校验状态为可入账、净应付大于 0、币种存在、商家存在、已绑定主账号且入账端口已配置；未通过时后台展示阻断项并禁用请求按钮。商家提现、代付或链上划转不由 AI 模块触发，商家余额到账后由 Money / 支付 / 财务模块的提现流程独立处理。真实资金四方对账验收可读取GET /api/v1/admin/ai/settlements/requests/{requestId}/reconciliation-evidence和GET /api/v1/admin/ai/settlements/{settlementId}/reconciliation-evidence，按 requestId 或结算单聚合输出 wallet、ai_usage_event、ai_merchant_ledger、ai_usage_adjustment和ai_merchant_settlement的只读证据、复算金额与差异码；该接口只辅助验收留痕，不触发提现或外部资金划转、不修改状态，也不替代合规 / 财务人工确认。 - 回显：响应
model回显用户请求的名字（自营官方名 / 第三方带后缀名），真实上游 provider / credential 只进 usage 快照与管理端审计，不破坏 OpenAI / NewAPI SDK 兼容。 - 账务快照与回溯：第三方商家模型每次成功调用都会在
ai_usage_event保存归属用户、命中商家、publishedName、baseModel和关联商家台账 ID，并把同一requestId/eventKey回链到ai_merchant_ledger.usage_event_id。商家台账同时保存试用作用域快照，历史免费次数、折扣、项目 / Key 归属和补贴口径不依赖当前绑定配置。用户用量明细、用户第三方模型账单、商家应收账单和平台收入报表可以围绕同一笔 usage 复算用户扣费、平台佣金、商家应收、试用减免和后续冲正，不依赖当前可变配置。 - 能力矩阵与 Key 策略：后台
AI 平台 > AI 能力矩阵和GET /api/v1/admin/ai/capabilities可查询 NewAPI / OpenAI Compatible 能力矩阵。Chat、stream、Responses、Embeddings、Rerank、图片、音频等基础能力可第三方商家化；Files、Uploads、Batches、Fine-tuning、Vector Stores、Assistants / Threads、Realtime、Organization / Project 管理等高风险或有存储副作用能力默认关闭给第三方商家。第三方商家模型请求会在上游调用前检查矩阵，未开放能力直接拒绝，不伪装透传成功。Gateway Key 还支持allowedCapabilities白名单，后台 Key 抽屉可配置允许能力；留空表示不限制，填写后 HTTP 网关与 Realtime WebSocket 都会按能力拒绝越权调用。 - 计费与分账（ADR-066/067）：扣费源统一为储值钱包（预占 → 结算，
requestId幂等，流式 done 才结算）；只有返回真实 token 用量，或流式断连时已有成功传输内容且能估算出正数 output token，才允许从预占进入实际扣费。响应缺 usage、usage token 全为 0、上游 / 服务端异常、无已传输内容或估算失败时只释放 / 解冻预占，不按估算预占额扣费、不生成商家应收台账。结算同事务内拆账，商家分成逐笔记ai_merchant_ledger，周期结算只入账到商家 Money 余额；商家后续提现不属于 AI 模块职责。
外部错误契约
网关 /api/v1/ai/gateway/** 的鉴权、访问策略、业务拒绝和模型调用失败一律以当前入口的协议原生错误体返回，不会出现平台 Result 包装。OpenAI Compatible / Codex 错误体形如：
{
"error": {
"message": "第三方商家模型未启用，请先在模型市场添加：gpt-4o@acme",
"type": "invalid_request_error",
"param": null,
"code": "model_not_enabled"
}
}OpenAI Compatible / Codex 的 error.code 一经发布不再变更，SDK 与自动化脚本可直接依赖：
| error.code | HTTP | 场景 | 建议处理 |
|---|---|---|---|
model_not_found | 404 | 商家 / 模型不存在、已下架或不可路由 | 检查 model 拼写；到模型市场确认模型是否仍在架 |
forbidden | 403 | Gateway Key 的模型、Provider、能力或 scope 访问策略拒绝请求 | 调整 Key 白名单 / scope，或改用已授权模型 |
model_not_enabled | 403 | 第三方模型未加入当前用户 / 项目 / Key 启用清单，且不在当前默认推荐商家模型清单 | 到控制台模型市场按需要的作用域启用后重试，或由管理员调整默认推荐数量 / 排序 |
merchant_unavailable | 403 | 商家未通过审核、被停用或处于沙箱 / 冻结 | 等待商家恢复；不会自动切换到其他商家 |
capability_unsupported | 403 | 该能力未对第三方商家开放（能力矩阵 fail-closed） | 改用平台自营模型或联系平台运营开通 |
trial_not_available | 403 | 上游调用前 TRIAL 绑定试用策略无效 / 额度耗尽，或试用结算 fallback 开关关闭后 settle 阶段仍不可用 | 在控制台把绑定显式转为付费后重试 |
merchant_marketplace_disabled | 403 | 平台全局关闭了第三方商家模型能力 | 平台自营模型不受影响，可直接改用官方名调用 |
budget_exceeded | 402 | 账号 / 项目 / 组织预算超限 | 调整预算策略或充值；请求未发起上游、未扣费 |
model_price_not_configured / billing_not_configured / billing_owner_required / billing_account_not_found | 400 | 定价 / 计费配置缺失 | 商家侧补定价；平台侧检查计费装配 |
request_rejected | 400 | 其余业务拒绝的兜底 | 按 error.message 提示处理 |
Claude /claude/v1/** 使用 Anthropic type=error envelope、request-id / request_id 和流式 SSE event: error，不提供 OpenAI error.code；具体格式见 AI 模型网关。
除 trial_not_available 的 settle fallback 开关关闭场景外，以上拒绝均发生在上游调用之前：不扣费、不产生商家台账、不 fallback。TRIAL 请求如果已经 reserve 通过并完成上游调用，settle 阶段才发现试用权益因并发或策略窗口失效，默认不返回 trial_not_available，而是按付费全价结算并写入 ai_merchant_ledger.trial_fallback=true；关闭 spring.open.ai.gateway.billing.trial-settle-fallback-enabled 后恢复旧的 settle 抛错语义。上游 Provider 自身错误沿用既有透传 / 映射规则（见 AI 模型网关）。Realtime WebSocket 不返回 HTTP 错误体；第三方商家 Realtime 会使用同一套 OpenAI Realtime 兼容 error 事件 + 1008 close reason 表达拒绝或会话中失败。默认能力矩阵仍对商家 Realtime 关闭，因此未开放时仍返回 capability_unsupported；当运营开启 realtime.merchant_supported 且 Gateway Key / 用户 / 预算 / 访问策略全部通过时，握手复用 HTTP 商家路由与商家渠道配置，按 spring.open.ai.gateway.realtime.merchant-session-max-tokens 预占，正常关闭按上游 response.done.usage 或文本估算结算，异常断开或上游未就绪关闭释放预占；上游连接失败返回 merchant_unavailable，会话用量超过上限返回 budget_exceeded。
灰度与回滚开关
第三方商家能力支持八层独立开关，任一层关闭都不影响平台自营模型：
| 层级 | 开关 | 生效表现 |
|---|---|---|
| 全局 | spring.open.ai.gateway.merchant-marketplace-enabled=false | 所有 model@merchant 调用与市场启用返回 merchant_marketplace_disabled，模型市场为空 |
| 默认推荐 | spring.open.ai.gateway.recommended-merchant-model-count=0 | /models 不再默认追加推荐商家模型，只返回平台自营与显式启用模型 |
| 商家 | 后台停用商家（SUSPENDED）或回滚沙箱（back-to-sandbox）；结算可单独冻结 | 该商家全部模型返回 merchant_unavailable |
| 模型 | 商家 / 后台把模型 publish_status 置 OFFLINE 或停用 | 该模型返回 model_not_found |
| 能力 | 能力矩阵 merchant_supported=false；Gateway Key allowedCapabilities 白名单 | 返回 capability_unsupported |
| 用户 / Key | 商家访问治理策略黑白名单；禁用 Gateway Key | 预占前拒绝，不调上游 |
| 试用结算 | spring.open.ai.gateway.billing.trial-settle-fallback-enabled=false | TRIAL 请求在 settle 阶段试用权益竞态失效时恢复旧的 trial_not_available 抛错语义；默认开启时按付费全价结算并写 trial_fallback |
| 结算 | 默认 money-balance 入账；AI 模块不触发代付、提现或链上划转 | money-balance 会把净应付幂等写入商家主账号 Money 余额并同步标记 PAID；提现由 Money / 支付 / 财务模块独立处理 |
配置入口
spring:
open:
ai:
enabled: true
platform:
enabled: true
gateway:
enabled: true| 配置 | 默认值 | 说明 |
|---|---|---|
spring.open.ai.enabled | true | 是否启用 AI 业务模块 |
spring.open.ai.platform.enabled | true | 是否启用 AI 平台控制面接口 |
spring.open.ai.gateway.enabled | true | 是否启用 AI 模型网关接口 |
spring.open.ai.gateway.merchant-marketplace-enabled | true | 第三方商家模型全局开关（灰度第一层）；关闭后商家路由与市场启用明确拒绝，平台自营不受影响，GET /api/v1/ai/gateway/status 暴露 merchantMarketplaceEnabled |
spring.open.ai.gateway.recommended-merchant-model-count | 完整应用 10 / 模块与 schema 0 | 网关模型发现接口默认追加的推荐第三方商家模型数量；按市场置顶 / 排序分筛选，后台可改成 100 等更高数量，0 表示关闭默认推荐 |
spring.open.ai.gateway.realtime.merchant-session-max-tokens | 65536 | 商家 Realtime 会话握手预占与会话上限使用的 token 预算；小于等于 0 时商家 Realtime 拒绝，平台自营 Realtime 不受影响 |
spring.open.ai.gateway.rate-limit.distributed-concurrent-enabled | true | Redis 管理器可用时，App / Key / 用户 / Provider 最大并发许可通过 Redis 在多实例间共享；无 Redis 时自动退回单进程计数 |
spring.open.ai.gateway.rate-limit.concurrent-permit-ttl | PT2M | Redis 最大并发许可自动过期时间，用于节点异常退出后释放残留许可 |
spring.open.ai.gateway.billing.money.asset-code | points:AI_TOKEN | AI 网关扣费和商家余额结算共用的 Money 储值资产；默认使用 AI token 点数资产 |
spring.open.ai.gateway.billing.money.decimals | 8 | AI Money 储值钱包精度；默认与商家价格 / 台账快照保持 8 位，避免真实低 token 调用在钱包层向下取整成 0 后缺失资金流水 |
spring.open.ai.gateway.billing.trial-settle-fallback-enabled | true | TRIAL 请求 reserve 已通过但 settle 阶段试用权益竞态失效时，是否降级按付费全价结算并写入 trial_fallback 审计快照 |
spring.open.ai.provider-config-cache-ttl | PT10S | Provider 覆盖配置与凭证池的进程内快照缓存时长；后台保存 Provider / 商家渠道 / 凭证后主动失效，设 0 关闭缓存（每请求直查数据库） |
spring.open.ai.merchant-settlement.auto-release.enabled | true | 结算单超时后是否自动执行 readiness 检查并放行正常结算单 |
spring.open.ai.merchant-settlement.auto-release.auto-startup | true | 启动时是否自动注册兜底调度任务；Queue 延迟任务仍是主路径 |
spring.open.ai.merchant-settlement.auto-release.timeout | 24h | 结算单等待人工审核的超时时间，超过后由队列或兜底调度自动处理 |
spring.open.ai.merchant-settlement.auto-release.fixed-delay | 10m | Scheduler 兜底扫描间隔 |
spring.open.ai.merchant-settlement.auto-release.task-name | ai.merchant-settlement.auto-release | Queue / Scheduler 共用任务名称；Queue 消费者固定使用 ai-merchant-settlement 队列 |
spring.open.ai.merchant-settlement.auto-release.instance-id | default | Scheduler 兜底任务实例 ID |
spring.open.ai.merchant-settlement.auto-release.limit | 100 | 兜底扫描单次最多处理的结算单数量 |
spring.open.ai.merchant-settlement.auto-release.request-payout | true | 自动放行通过后是否立即请求余额入账 Provider；关闭后只自动进入 PAYABLE |
spring.open.ai.merchant-settlement.auto-release.freeze-on-blocked | true | 自动检查不通过或自动入账异常时是否冻结为 FROZEN 等待人工复审 |
快速启动与运营模板种子
全新开发库会通过迁移基线预置一组运营模板数据，避免刚启动时模型目录、价格和倍率全空。正式基线不预置本地样例 Gateway Key，也不预置任何用户 AI_TOKEN 余额；需要本地 smoke 时，先在后台创建测试 Key，并通过充值、后台手动调整或业务入账准备余额 / quota。
| 归属 | 预置内容 | 用途 |
|---|---|---|
| Money | 预置 points:AI_TOKEN 资产目录展示名，不预置任何用户余额 | 正式调用前需通过充值、后台手动调整或业务入账为调用用户准备可用余额，避免生产部署误带测试额度 |
| 运营模型目录 | deepseek/deepseek-chat、deepseek/deepseek-reasoner、openai/gpt-4.1-mini、openai/gpt-4o-mini、openai-compatible/default-chat、newapi/gpt-4.1-mini、openrouter/openai/gpt-4o-mini、local-account-pool/local-chat | 常见 Provider 的模型目录模板，后台模型列表和 /models 不再空白 |
| 运营价格模板 | 上述模型均预置非零 CNY 模板价，默认成本价等于售价 | 报表、用量事件、成本快照有基准数据；避免真实模型误按 0 价展示 |
| 运营 quota 倍率 | 上述模型均预置 ai_model_ratio，普通模型接近 1 倍，推理 / OpenAI 类模型更高 | 钱包扣费可按模型差异消耗 quota；上线后可在后台“额度倍率”改成真实计费策略 |
这些种子用于新库初始化，不写入真实 API Key，也不会用数据库覆盖关闭 application.yml / env 的 Provider 配置；真实上游是否启用仍以 env 或后台 Provider 配置为准。生产部署应配置真实 Provider 凭证、价格、倍率、用户 / Key 额度、限流、商家结算策略和调用用户余额。
DeepSeek 最短 env 示例：
SPRING_OPEN_AI_MODEL_DEFAULT_PROVIDER=deepseek
SPRING_OPEN_AI_MODEL_PROVIDERS_DEEPSEEK_ENABLED=true
SPRING_OPEN_AI_MODEL_PROVIDERS_DEEPSEEK_MODEL=deepseek-chat
SPRING_OPEN_AI_MODEL_PROVIDERS_DEEPSEEK_API_KEY=sk-your-deepseek-keyDeepSeek 的应用默认 base-url 已内置 https://api.deepseek.com/v1，普通真机联调只需要配置模型名和 API Key；只有接入代理、企业网关或私有转发入口时才需要覆盖 SPRING_OPEN_AI_MODEL_PROVIDERS_DEEPSEEK_BASE_URL。
通用 OpenAI Compatible 端点最短 env 示例：
SPRING_OPEN_AI_MODEL_DEFAULT_PROVIDER=openai-compatible
SPRING_OPEN_AI_MODEL_PROVIDERS_OPENAI_COMPATIBLE_ENABLED=true
SPRING_OPEN_AI_MODEL_PROVIDERS_OPENAI_COMPATIBLE_MODEL=default-chat
SPRING_OPEN_AI_MODEL_PROVIDERS_OPENAI_COMPATIBLE_BASE_URL=https://your-compatible-endpoint/v1
SPRING_OPEN_AI_MODEL_PROVIDERS_OPENAI_COMPATIBLE_API_KEY=sk-your-compatible-key如果走后台配置而不是 env：进入 业务模块 > AI 平台 > AI 运营，启用对应 Provider，补 baseUrl、默认模型和 API Key；再到模型目录 / 模型价格 / 额度倍率确认 quickstart 模板是否符合当前上游价格。调用方 Key 建议在后台新建正式 Key；本地样例 Key 只用于 localhost smoke。
结算入账通道是 SPI：AI 模块通过 AiMerchantSettlementPayoutProvider 管理余额入账 Provider，默认 money-balance Provider 会按 spring.open.ai.gateway.billing.money.asset-code 把净应付金额幂等写入商家主账号 Money 余额账户，幂等键为 ai:merchant:settlement-credit:money-balance:{settlementId}，并在同一事务内把结算单标记为 PAID。payout* 字段、接口路径和 request-payout 操作名保留为历史 contract 名称；当前语义均为“请求结算入账”，不表示 AI 模块会触发外部资金划转。AI 模块不内置 payment、web3-token、银行代付或链上划转 Provider，商家提现由 Money / 支付 / 财务模块独立承担。
发版或部署验收前，可执行 ./scripts/release ai-b2b2c-acceptance --settlement-provider money-balance 生成 AI B2B2C 余额入账、资金四方对账和 Release Gate 终审 runbook。验收记录填写完成后，再执行 ./scripts/release ai-b2b2c-gate --record <file> 校验记录是否包含合规 / 税务 / 风控 / 财务放行、余额入账引用、四方对账和发版口径证据；其中 Release Gate 会按 SDK / 协议兼容、自营 + 商家闭环、模型列表可控、路由隔离、计费幂等、账务复算、密钥日志安全、前端运营、结算控制、真实上游 smoke 和回滚层逐项检查，不接受只写一个总结果替代逐项证据。gate 通过后可执行 ./scripts/release ai-b2b2c-archive --record <file> 生成本地归档包，包含记录副本、gate 输出和归档说明。三个命令都只读取 / 输出记录，不调用上游模型、不移动资金、不修改数据库，也不能替代外部证据真实性审查。
这些核心开关、网关 Key 鉴权、Realtime、限流、健康快照、计费和凭证治理配置已由 AiServiceProvider 声明到 lifecycle 配置 schema，后台配置中心可发现 AI 模块运营主干配置；Provider 动态实例仍由 AI 模型平台和 Provider 配置管理维护。
两条部署与运营语义需要预先知晓：
- 最大并发许可优先使用 Redis 共享：网关的窗口限流（每分钟 / 每天）经
RateLimitManager，接入 Redis 后天然多实例共享；App / Key / 用户 / Provider 的最大并发数在RedisManager可用且spring.open.ai.gateway.rate-limit.distributed-concurrent-enabled=true时通过 Redis 共享许可和短 TTL 自动释放，适合多实例部署。无 Redis 或显式关闭该开关时退回进程内计数，单实例无影响；多实例单机退回模式下实际并发上限≈单节点上限×节点数。 - 流式断连按「已传输即按量结算」（ADR-072，默认开启）：客户端在 SSE 传输中途主动断开时，只对已成功传输给客户端的 delta 按 token 估算做部分结算（
input=0，不计 prompt / 未传输 / 最终完整响应）；服务端 / 上游异常、无已传输内容或估算失败仍失败即免单整体释放（不扣费、不落台账，钱包预占解冻）。断连统一在ai_usage_event以result_code=499归类；部分结算事件额外billable=true且带client-abort-partial-settlement标记，商家台账经 usageEventId 回链。启用即改变默认计费语义，运营须配套公告 / 用户协议 / 风控策略；可显式spring.open.ai.gateway.abort-settlement.enabled=false回到失败即免单。abort-guard断连逃费风控（ADR-071，默认关闭）与之独立并存。
AI 模型调用底座的 Provider 配置见 AI 模型。
第一版方向
第一版目标不是一次性做全模型、全协议和全运营后台，而是先形成可上线运营的最小闭环：
- AI 模型 starter 优先支持 OpenAI Compatible 公共 Provider，并通过配置实例优先接入 DeepSeek；同时继续补真实 Provider 回退链和更完整上游错误映射。
- AI 模型平台管理供应商、模型别名、用户 API Key、价格和调用日志；新后台入口从
/api/v1/admin/ai/platform/**开始落地。 - AI 模型网关路径为
/api/v1/ai/gateway/**，已开放 OpenAI Compatible/models//v1/models和普通 / 流式chat/completions、Claude/claude/v1/models/ 普通与流式/claude/v1/messages、Codex/codex/v1/models/ 普通与流式/codex/v1/responses。 - 计量计费接入 Money / Billing，形成 token 计量、余额 / 套餐扣费、成本和毛利记录。
- Admin 和用户侧视图补齐供应商运维、Key 管理、用量明细和接入文档。
商业计划和阶段讨论放在 storage/designs/ai/，正式工程 contract 以本目录文档和 .ai/tasks/archive/2026/07/2026-07-04-ai-platform.md 为准。