# 大模型服务封装Skill

> LLM 调用封装模式:流式输出、重试限流、多模型路由、降级。当需要封装大模型调用服务(统一接入、容错与多模型路由)时使用。

- Skill: `sky-cube/skill-43` (Agent Skill)
- Install (CLI): `npx skillmds@latest add sky-cube/skill-43`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sky-cube/skill-43/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Sky-Cube (https://skillmd.com/u/sky-cube)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sky-cube/skill-43

---

# 大模型服务封装Skill

## 适用场景
封装统一的大模型调用服务:屏蔽多厂商差异,提供流式输出、重试、限流、多模型路由与降级能力,业务侧只依赖本服务。

## 执行步骤
1. 定义统一接口:入参(消息、参数、场景标识)、出参(内容、Token 用量、模型标识、延迟),同步与流式(SSE/回调)双形态。
2. 配置管理:各模型 endpoint、密钥、超时、限流阈值全部走配置中心/环境变量,禁止硬编码;密钥支持轮换。
3. 超时与重试:同步请求设超时;429/5xx 采用指数退避重试(上限 3 次,加抖动防惊群),超时或重试耗尽进入降级。
4. 限流:按厂商配额、场景、租户三层限流(令牌桶),排队或快速失败由调用方选择。
5. 多模型路由:规则可配置(默认/低成本/高精度/长上下文),支持按场景路由与灰度切换,支持 fallback 链(主→备→本地小模型)。
6. 降级兜底:模型全部不可用时的策略分级——缓存命中答案、模板回复、明确报错;禁止静默编造。
7. 可观测:每请求记录 traceId、模型、耗时、Token 用量、重试次数,失败告警。

## 规范要点
- 业务代码禁止直接调用厂商 SDK,必须经本封装层,保证密钥、限流、审计统一。
- 流式接口必须支持中断与超时清理,防止连接泄漏;SSE 断连需有重连或兜底策略。
- 重试仅限幂等操作(生成类重试产生费用,需上限控制);工具调用类请求谨慎重试。
- 结构化输出(JSON)必须 schema 校验,校验失败重试 1 次后报错,禁止吞异常。
- Token 计费统计必须落地,供成本分析与配额控制。
- 敏感内容(密钥、用户隐私)禁止写入日志。

## 输出模板
```
## LLM 服务封装方案
统一接口定义:方法签名 + 入参出参 + 流式形态
配置项清单:模型/endpoint/超时/限流/重试参数(密钥引用配置中心,不落明文)
路由与降级规则表:场景 → 主模型 → 备选 → 兜底策略
监控指标:调用量/成功率/延迟/Token 用量/降级次数
```

## 自检清单
- [ ] 统一接口屏蔽厂商差异,业务不直连 SDK
- [ ] 密钥无硬编码,超时/重试/限流参数齐全
- [ ] 流式支持中断与超时清理,无连接泄漏
- [ ] 降级链路闭环:主→备→兜底→明确失败
- [ ] Token 用量与失败率可观测可告警