OpenAI 兼容迁移：别忽略 SDK 的默认行为

同样的调用代码，只替换 base_url 后能返回，并不代表运行策略没有变化。不同语言和 SDK 版本，可能在超时、自动重试、代理读取、连接复用、JSON 解析与流式关闭上采用不同默认值；故障时，一次业务请求甚至可能被重试放大为多次模型调用。

迁移前建议把关键项显式写进配置：
1. 锁定并记录 SDK 版本，升级单独做变更；
2. 按实际库能力设置连接、读取和总超时；
3. 明确哪些状态允许重试，限制次数并记录每次尝试，避免重复扣费或重复业务动作；
4. 在真实部署网络中验证代理、证书与连接释放；
5. 将流式、非流式、主动取消和异常响应分别测试。

每次只改一个变量，保存请求参数、状态码、耗时及脱敏请求标识，通过后再逐步切换流量。模型名称与当前价格：https://wmai7.io/models
快速文档：https://wmai7.io/docs/quickstart

模型选择：先定义“角色”，再绑定具体模型

把模型名称散落在业务代码里，后续调整会变成全仓搜索，测试与回滚也容易失控。更稳妥的做法是先定义逻辑角色，例如 fast、reasoning、vision，由配置层把角色映射到当前模型名。

落地时建议：
1. 每个入口只请求逻辑角色，不直接写模型名；
2. 为每个角色记录必要能力、最大可接受延迟、输出格式和单次成本上限；
3. 更换映射前，用同一批脱敏样本回归准确性、格式通过率和耗时；
4. 先小比例切换，保留旧映射作为可控回退；
5. 日志同时记录逻辑角色、实际模型和配置版本，便于定位差异。

注意：回退模型不一定支持完全相同的上下文长度、图片、工具调用或结构化输出，切换前应按实际能力验证，不要只改名称。

模型名称与当前价格：https://wmai7.io/models
快速文档：https://wmai7.io/docs/quickstart

流式与非流式：统一“完成判定”，别靠界面猜

同一业务如果同时支持 stream=true 和普通响应，最容易出错的不是展示方式，而是客户端对“请求完成”的定义不一致。非流式通常在一个 JSON 中拿到完整结果；流式则需持续消费增量，直到结束事件或连接正常收尾。仅看到几段文字，不能证明响应已经完整。

建议把两种模式收敛为同一结果结构：
1. 保存模型、请求开始/结束时间和最终文本；
2. 单独记录正常结束、用户取消、超时、网络中断与服务端错误；
3. 若响应提供 finish_reason 或用量字段，按实际返回保存，不要自行猜测；
4. 流式先拼接内容，确认正常完成后再标记成功；中途失败应提示重新生成，避免把残缺内容写入业务数据；
5. 用同一组脱敏样本比较完整性、首个输出延迟和总耗时，再决定哪些场景开启流式。

聊天界面适合流式提升体感；批量分类、结构化抽取更适合非流式后统一校验。

快速文档：https://wmai7.io/docs/quickstart
模型与当前价格：https://wmai7.io/models

Python、Node、cURL 联调：共用一份请求样本

排查“某语言能调用、另一种失败”时，先别换 SDK。固定同一 API 地址、模型名和参数，用 cURL 建立最小基线，再把相同 JSON 迁到 Python 与 Node：

POST /v1/chat/completions
Authorization: Bearer $API_KEY
Content-Type: application/json
{"model":"从模型页选择","messages":[{"role":"user","content":"返回 OK"}],"stream":false}

三端都记录状态码、响应体和耗时，但不要在日志中打印完整 Key。401 先核对密钥与 Authorization，400 比对模型名和 JSON 字段；429 或 5xx 按实际错误处理，避免无条件重试。若 cURL 成功而代码失败，检查环境变量、请求头、代理和 JSON 序列化。

快速文档：https://wmai7.io/docs/quickstart
模型与当前价格：https://wmai7.io/models

API Key 轮换：让旧 Key 有计划地退场

定期更换密钥时，最怕直接覆盖后出现集中 401。更稳妥的做法是把轮换当成一次小发布：

1. 在控制台创建新 Key，只写入密钥管理或环境变量，不进代码、聊天和日志；
2. 先更新一台测试实例，用最小请求确认鉴权正常，再分批更新其他实例；
3. 观察每个实例的 401、请求成功率与配置版本，确认全部都已切到新 Key；
4. 再删除旧 Key，并做一次反向检查：旧 Key 应失败，新 Key 应成功；
5. 若有 CI、定时任务、本地开发或备用环境，逐项清点，避免遗漏仍在使用旧 Key 的调用方。

不要把完整 Key 放进命令历史或截图；排障时只提供发生时间、错误码和脱敏尾号。不同环境、不同服务使用不同 Key，出现问题时影响范围更容易控制。

快速文档：https://wmai7.io/docs/quickstart
客服：@wmAi7_Bot

AI 网关上线：把“进程活着”和“服务可用”分开

生产部署时，健康检查若直接调用模型，可能增加延迟和用量，也会把短暂的外部波动误判为进程故障。更稳妥的做法是拆成两层：

1. 存活检查（liveness）：只确认进程和事件循环能响应，不访问模型；
2. 就绪检查（readiness）：确认配置已加载、路由可用、必要依赖可连接，未就绪的实例不接收新流量；
3. 另设低频合成探测：用最小、无敏感数据的请求验证完整调用链，单独统计状态码和耗时；
4. 发布时先等新实例就绪，再逐步切流；异常实例先摘流，再排查，不要依赖无限重启。

告警应区分本地故障、鉴权失败、限流和服务端错误，避免所有异常都归为“模型不可用”。排障日志只记录时间、状态码、请求标识和脱敏信息，不写完整 API Key。

快速文档：https://wmai7.io/docs/quickstart
模型与当前价格：https://wmai7.io/models

AI 客服分流：让答案带出处，也知道何时交给人工

AI 客服不该只追求“像真人说话”。更实用的起点，是让它先在已审核知识库中检索，再生成带来源编号的候选答复，并把无法确认的问题交给人工。

落地可拆成四步：
1. 每份规则或 FAQ 标注版本、适用范围和更新时间，只召回与问题相关的片段；
2. 要求答复同时返回引用编号，服务端校验编号是否真实存在；
3. 遇到账户归属、费用争议、身份信息等高风险问题，或检索结果不足、内容互相冲突时，不自动承诺，直接转人工；
4. 记录问题、知识版本、引用编号和人工修改原因，用于发现过期内容，不把未经审核的对话直接写回知识库。

试运行时可统计引用有效率、人工接管率、一次解决率和错误承诺数。AI 负责整理与建议，人仍负责需要授权或判断的决定。

模型名称与当前价格：https://wmai7.io/models
快速文档：https://wmai7.io/docs/quickstart

开发者 FAQ：system 提示词越长，效果越好吗？

不一定。system 用来定义长期角色、边界和输出约束，但把产品手册、示例、临时任务和全部历史都塞进去，会增加输入 token、占用上下文，也可能因规则互相冲突而降低一致性。

更稳妥的做法：
1. 只保留稳定且优先级最高的规则，如角色、禁止项、语言和输出格式；
2. 当前任务放在 user 消息，业务资料按需检索，只传与本次问题相关的片段；
3. 对结构化输出继续做 JSON 与 Schema 校验，不把“写了格式要求”当成结果保证；
4. 给提示词编号，用同一组脱敏样本回归，比较任务通过率、人工修正率、输入/输出 token 与实际扣费；
5. 发现规则冲突时先删减、排序和合并，不要只继续追加。

优化目标不是“提示词最短”，而是用更少歧义完成可验收任务。token 是模型处理内容的计量单位，不是可直接充值的固定套餐；平台余额按真实模型使用扣费。

快速文档：https://wmai7.io/docs/quickstart
模型与当前价格：https://wmai7.io/models

AI token 知识：工具返回越大，下一轮输入越重

在常见的工具调用流程中，模型先生成调用参数，应用执行搜索、数据库或业务接口，再把工具结果作为消息交回模型继续生成答案。容易被忽略的是：这份返回内容会进入后续请求的输入；把整页 HTML、完整日志或上千条记录原样塞回去，不仅增加 token，也可能让关键信息被噪声淹没。

更稳妥的做法：
1. 工具层按字段白名单提取，只返回完成任务必需的数据；
2. 搜索和数据库结果限制条数、字段与时间范围，超出时分页或摘要；
3. 错误日志只回传错误码、时间和必要上下文，完整原文留在自己的审计系统；
4. 给工具结果设置大小门槛，超限则停止并缩小查询；
5. 记录实际输入/输出 token 与工具结果大小，用脱敏样本验证答案质量没有下降。

token 是模型处理内容的计量单位，不是可直接充值的固定套餐；平台余额按真实模型使用扣费。

快速文档：https://wmai7.io/docs/quickstart
模型与当前价格：https://wmai7.io/models

API 接入教程：别把 HTTP 200 直接当业务成功

完成首次调用后，建议把响应验收分成三层：
1. 传输层：确认 HTTP 状态码、Content-Type 与响应体可读取；非 2xx 先记录状态码和脱敏后的错误正文，不要直接进入 JSON 解析。
2. 协议层：解析 JSON 后检查必需字段、数据类型以及错误对象；不要只凭“有返回内容”判断成功。流式调用则按完整事件帧处理，并确认正常结束信号。
3. 业务层：确认答案非空、格式符合你的约束；结构化输出还应经过 Schema 校验，再交给下游流程。

测试时至少覆盖正常响应、401、限流或服务端错误、超时和流式中断。日志保留发生时间、状态码、请求追踪信息（若响应提供）与脱敏参数，绝不记录完整 API Key。只有三层都通过，才把这次调用计为成功。

快速文档：https://wmai7.io/docs/quickstart
模型与当前价格：https://wmai7.io/models

OpenAI 兼容迁移：给模型调用留一条回退路

把现有项目迁移到兼容接口时，最容易返工的做法，是让业务代码直接依赖某个 SDK 的请求和响应对象。更稳妥的方式，是先在应用内建立一层轻量适配器：业务层只传统一字段，如 model、messages、temperature、stream；适配层负责组装请求、读取文本、映射错误，并把结果转换成自己的数据结构。

迁移可分四步：
1. 用一组脱敏固定样本记录原链路的输出格式、延迟和错误表现；
2. 先接通非流式最小请求，再单独验证流式增量、结束信号和取消；
3. 对实际用到的参数做白名单，不要假设每个扩展字段都能原样通用；
4. 通过配置切换旧、新连接，保留短期回退开关；若校验失败，只回切链路，不重复执行业务副作用。

上线判断不要只看“能返回文字”，还要检查 HTTP 状态、结构化字段、超时、限流与日志脱敏。先灰度少量请求，再逐步扩大。

快速文档：https://wmai7.io/docs/quickstart
模型与当前价格：https://wmai7.io/models

模型选择：先定淘汰线，再谈主力模型

不要先问“哪个模型最好”，先问“这个任务怎样才算合格”。可以为每类业务建立独立验收卡：
1. 摘要：关键事实不得遗漏，字数与格式必须通过规则校验；
2. 信息抽取：字段类型、必填项、枚举和原文依据要可检查；
3. 客服问答：答案必须引用允许的知识来源，无法确认时应明确转人工；
4. 代码辅助：至少通过目标仓库的测试、静态检查和人工审查。

把硬门槛与优化指标分开：硬门槛没过，即使响应更快、单次费用更低也不进入候选；都过关后，再比较合格率、延迟和完成一个有效任务的实际成本。上线时按任务配置主模型与备用模型，并写清切换条件；若请求涉及扣款、发信等副作用，超时后不要盲目重试或切换，以免重复执行。

用脱敏真实样本定期复测。模型名称与当前价格：https://wmai7.io/models
快速文档：https://wmai7.io/docs/quickstart

流式还是非流式？先看用户能否中途改变主意

选择 stream=true，不只是为了“更快看到字”。如果用户需要边看边停止、修改问题或判断方向，流式更合适；客户端应把“停止”连接到请求取消，并明确区分用户取消、网络中断和服务端错误。收到部分文本时，只把它当作未完成草稿，不要立即触发发信、扣款、写库等后续动作。

非流式更适合后台摘要、分类、结构化抽取等需要拿到完整结果再校验的任务：先检查 HTTP 状态与响应结构，再执行 schema 或业务规则；失败时记录可追踪信息，按幂等条件决定是否重试。

一个实用做法是让前端负责展示增量，服务端在完整成功后再提交最终结果。这样既保留交互体验，也避免半截内容进入正式流程。若用户取消，界面可保留已显示文字供参考，但后台状态应标记为未完成。

快速文档：https://wmai7.io/docs/quickstart
模型与当前价格：https://wmai7.io/models

Python/Node/cURL 调试：统一留痕，不要打印密钥

同一接口在三种工具里表现不一致时，先记录可比较的信息：请求时间、模型名、HTTP 状态码、耗时、响应中的错误类型与错误消息，以及服务端返回的请求标识（若响应头或响应体提供）。这些字段通常比整段原始响应更适合排障。

cURL 可用 -i 或 -D - 临时查看响应头；Python requests 读取 status_code、响应头和解析后的错误 JSON；Node.js fetch 记录 res.status，再按 Content-Type 决定解析 JSON 还是文本。生产日志应设置长度上限并脱敏，只保留必要片段。

切勿打印完整 Authorization 请求头、API Key、Cookie 或用户原始敏感内容；遇到 401，只记录“鉴权失败”和密钥脱敏尾号。向客服排障时，可提供发生时间、请求标识、HTTP 状态、模型名和脱敏后的错误摘要。

快速文档：https://wmai7.io/docs/quickstart
客服：@wmAi7_Bot

费用控制：别只看单次调用，要看“合格结果成本”

单次请求价格低，不代表最终业务成本低。格式校验失败、超时后的重复调用、无效输入和人工返工，都可能让同一项任务消耗多次模型用量。更实用的指标是：完成一个被业务接受的结果，总共花了多少。

落地时可给每个业务任务分配唯一编号，并汇总请求次数、输入/输出 token、实际扣费、错误类型、校验结果与最终是否采用。统计时把技术失败、结构校验失败、用户取消分开看，才能判断问题在模型、提示词、网络还是流程。

重试要设置上限和退避，只对明确可重试且满足幂等条件的请求执行；参数错误或鉴权失败应先修正，不要自动重复。涉及发信、写库等副作用时，更要避免盲目重放。

token 是模型处理内容的计量单位，不是固定充值套餐；平台余额按真实模型使用扣费。模型与当前价格：https://wmai7.io/models

生产环境实践：把超时当成一份共享预算

生产链路常经过网关、业务服务、模型接口和任务队列。若每一层都单独等待 60 秒，用户请求可能远超预期才失败；更稳妥的做法是入口生成一个截止时间，并把“剩余可用时间”沿链路传递。

落地时可拆成三段：连接与首包、持续读取、业务收尾。每次调用前重新计算剩余时间，为日志写入任务编号、当前阶段、已耗时和失败类型；剩余预算不足时应尽早终止，不再启动新的模型调用。重试也应消耗同一份预算，只对明确可重试且不会重复产生副作用的操作执行，并设置次数上限与退避。

后台任务可拥有不同预算，但仍要记录最终状态；涉及写库、发信等动作，先确认模型结果完整并通过业务校验，再用幂等键防止重复提交。

快速接入文档：https://wmai7.io/docs/quickstart
客服：@wmAi7_Bot

AI 应用场景：把自动化拆成“建议、校验、执行”三层

把 AI 接进工单、邮件或运营后台时，可以先把流程分开：模型读取完成任务所需的上下文，输出“建议动作、理由、结构化参数”；规则层检查动作是否在白名单、字段是否完整、是否涉及发信、退款、封禁等外部影响；执行层只接受通过校验，并满足人工批准或既定自动化权限的请求。

落地时建议：
1. 只读查询和内部草稿可先开放自动处理；
2. 发送消息、修改订单、删除数据等动作设置确认门槛；
3. 每个执行请求携带唯一 idempotency_key，避免超时重试造成重复操作；
4. 记录提示词版本、建议结果、审批与最终状态，便于复盘。

这样模型负责提高整理效率，业务系统仍保留最终控制权。

接入参考：https://wmai7.io/docs/quickstart
客服：@wmAi7_Bot

开发者 FAQ：为什么 JSON 能解析，接口仍然报错？

“能被 JSON 解析”只证明语法合法，不代表请求满足接口约定。排查时可以分三层：
1. 语法层：引号、逗号和转义正确，请求正文按文档使用 JSON；
2. Schema 层：必填字段齐全，字符串、数组等类型正确，字段名与枚举值符合文档；
3. 业务规则层：模型标识有效，业务必需内容不为空，字段组合满足接口约束。

先保存一份不含 API Key 和敏感原文的最小请求，用 cURL 复现，再逐项加入可选参数。不要看到 400 就盲目重试：参数不变，重复请求通常不会修复结构错误。日志可保留时间、HTTP 状态、错误类型和脱敏后的请求摘要，便于定位。

快速文档：https://wmai7.io/docs/quickstart
客服：@wmAi7_Bot

AI token 知识：历史消息不是免费的“背景”

在多数对话式 API 中，模型只会处理本次请求实际提交的内容；如果客户端每轮都把完整 messages 历史重新带上，旧对话会再次进入本轮输入计量。对话越长，后续单次请求的输入通常越大。token 是模型处理内容的计量单位，不是可直接充值的固定套餐；平台余额按真实模型使用扣费。

控制上下文可以分三步：
1. 保留系统规则、当前任务目标和仍会影响答案的关键事实；
2. 将已完成的多轮讨论压缩为简短摘要，删除重复确认、无关工具输出和过期样例；
3. 裁剪后做一次回归检查，确认约束、标识和待办没有丢失。

不要为了省 token 直接清空历史；目标是保留“完成当前任务所需的信息”，而不是保留“发生过的一切”。开发时可分别记录输入、输出和总用量字段，再结合实际任务结果观察裁剪效果。

快速文档：https://wmai7.io/docs/quickstart
模型与当前价格：https://wmai7.io/models

API 接入教程：复用 HTTP 客户端，但别共享业务状态

在常驻服务里，不要每次调用都临时创建 HTTP 客户端。把 Base URL、认证头、连接超时和连接池配置集中初始化，业务请求只传模型、messages 等当次参数。这样有机会复用已有连接，减少重复建连开销，也便于统一升级和排障。

落地时注意：
1. 客户端可以复用，messages、用户标识和请求体不能放进全局可变对象；
2. 不要在并发请求中修改共享 headers；需要变化的字段按请求传入；
3. 为连接、读取和整次任务分别设置边界，记录“等待连接”和“等待响应”的耗时；
4. 应用退出时按 SDK 约定关闭客户端，避免资源悬挂。

先用最小请求验证，再逐步增加并发；出现问题时先检查连接池是否耗尽、代理是否生效和超时发生在哪一段，而不是盲目重试。

快速文档：https://wmai7.io/docs/quickstart
模型与价格：https://wmai7.io/models