Client (OpenAI 协议)
  ↓
ai-security-guard  内容合规
  ↓
jwt-auth / key-auth
  ↓
ai-intent         意图识别 → 路由分流
  ↓
ai-token-ratelimit / ai-quota
  ↓
ai-cache          (命中即返回)
  ↓
ai-rag            注入上下文
  ↓
ai-history        历史会话
  ↓
ai-prompt-template / decorator
  ↓
ai-proxy          协议转换 → 转发到 LLM
  ↓
ai-statistics     记账

20 多个 AI 相关插件按 phase + priority 组成流水线。Higress 默认提供 ai-* phase 推荐顺序。

extensions/ai-proxy/
  main.go             # 注册 SetCtx
  config.go           # ProviderConfig schema
  provider/
    provider.go       # ★ Provider 接口 + 工厂
    openai.go         # 直通
    azure.go
    qwen.go
    deepseek.go
    moonshot.go
    claude.go
    gemini.go
    cohere.go
    ollama.go
    ...20+ 个

type Provider interface {
    GetProviderType() string
    OnRequestHeaders(ctx, apiName, log) error
    OnRequestBody(ctx, apiName, body, log) (types.Action, error)
    OnResponseHeaders(ctx, apiName, log) (types.Action, error)
    OnStreamingResponseBody(ctx, apiName, chunk, isLast, log) ([]byte, error)
    OnResponseBody(ctx, apiName, body, log) (types.Action, error)
}

"4 个生命周期 + Streaming 钩子" 是适配 LLM 协议的统一抽象。

所有 Provider 对外都用 OpenAI 协议入参。openai.go 是恒等转换（直接转发）。其它 Provider 在 OnRequestBody 阶段读取 OpenAI request → 改写为对应厂商 schema；响应阶段反向。

provider/qwen.go：

• 请求映射：messages → input.messages；model → DashScope 模型名。
• 响应映射：output.text → choices[].message.content；usage 字段名稍异。
• 支持流式：每个 SSE chunk 改写后转发。

provider/claude.go 处理 Anthropic 协议：

• system 消息 → 顶层 system 字段（不在 messages 数组）。
• stop_reason 映射回 OpenAI 的 finish_reason。
• Tool use 协议差异较大，需要特别处理。

provider/gemini.go：

• 路径：/v1beta/models/{model}:generateContent。
• messages → contents 数组，role 名 "user/model"。
• generationConfig 字段映射 temperature / topP。

Azure OpenAI 与官方 OpenAI 协议几乎一致，差异：

• URL 路径含 deployment：/openai/deployments/{deployment}/chat/completions。
• 认证用 api-key header 不是 Authorization。
• API version query 参数。

OnStreamingResponseBody 每来一段 chunk 调用一次。注意：

• isLastChunk 决定是否要 flush 内部 buffer。
• 多个 chunk 可能跨 SSE 事件边界，要重新拼装。
• Higress 提供 EventStreamParser 工具帮助按事件划分。

extensions/ai-token-ratelimit：按 token 数量限流（不是按 QPS）。请求阶段先用 tokenizer 估算 prompt token，响应阶段把 usage.total_tokens 扣账，超阈值即下次拒绝。后端依赖 Redis。

面向多租户：按用户 / 团队 / API key 设置月度配额。与 ai-token-ratelimit 的区别：粒度（用户）+ 时间窗（月）+ 持久化（Redis hash）。

支持两种缓存：

• 精确缓存：以 messages 字面做 key，最简单。
• 语义缓存：调 embedding API → 向量化 → 相似度查询（向量库）。

命中时直接 SendHttpResponse 返回缓存，跳过 ai-proxy。

把请求的 query 发给向量库（Aliyun DashVector / Milvus / 阿里云搜索等），把召回的 chunks 注入到 messages 的 system 字段或 user 之前。

把历史会话从 Redis / 持久化层拉出来，自动拼到 messages 前面，让无状态客户端拥有有状态会话能力。session_id 通常通过 header / cookie 传入。

用一个小模型分类用户意图（购票 / 投诉 / 闲聊），根据结果改写 model 字段或 route 名，分流到不同 Provider。这是"AI 路由"。

把请求 / 响应内容送到内容合规服务（阿里云绿网 / 自研敏感词），命中即拦截。两阶段：请求拦敏感问题，响应拦敏感答案。

埋点：记录每次调用的 model / tokens / 耗时 / cache hit 等。Higress 把它落到 access log 字段，可由 Promtail / Loki / SLS 消费。

对多 Provider / 多 API key 做智能负载：

• 按健康度（失败率）熔断。
• 按延迟选择最快。
• 按 quota 剩余分配。

更高层能力：

• ai-search：让 LLM 调用搜索引擎补全实时信息。
• ai-agent：把 function calling 与外部工具串成 Agent flow，可在网关层完成简单 Agent。

步骤：

1. 在 provider/ 新建 my.go，实现 Provider 接口。
2. 在 provider.go 的工厂 switch 加 case "my"。
3. 在 config.go 加该 provider 的字段。
4. 写单测：构造 OpenAI request → 调 OnRequestBody → 校验改写后的 body。
5. build → 替换 ai-proxy 镜像。

整个过程不需要触碰控制面任何代码。