内容
# AI 网关示例
演示如何使用 [Ferro Labs AI 网关](https://github.com/ferro-labs/ai-gateway) — 一个用 Go 编写的开源 AI 网关，具有统一的 API，支持 OpenAI、Anthropic、Bedrock、Azure 和 100 多个大型语言模型（LLMs）。
## 目录结构
```text
.
├── basic/ # 直接提供者请求 - 最简单的用例
├── streaming/ # 流式聊天完成（实时 token 输出）
├── custom-plugin/ # 编写和注册自定义插件
├── embedded/ # 将网关嵌入现有的 HTTP 服务器
├── fallback/ # 自动在提供者之间切换
├── loadbalance/ # 跨多个提供者的加权负载均衡
├── with-circuit-breaker/ # 每个提供者的断路器配置
├── with-guardrails/ # 内置的词过滤和 token 限制防护
├── with-hooks/ # 用于遥测和审计日志的事件钩子
├── with-mcp/ # MCP（模型上下文协议）工具调用集成
└── shared/ # 共享提供者助手（所有示例都使用）
```
## 快速入门
### 先决条件
- Go 1.22+ — [安装](https://go.dev/dl/)
- 至少一个大型语言模型提供者的 API 密钥（OpenAI、Anthropic、Groq、Gemini、Mistral、Together、Cohere 或 DeepSeek）
### 运行示例
```bash
# 设置提供者 API 密钥
export OPENAI_API_KEY=sk-...
# 或
export ANTHROPIC_API_KEY=sk-ant-...
# 或任何其他支持的提供者密钥
# 运行基本示例
go run ./basic
```
## 示例
### basic
向配置了 API 密钥的第一个提供者发送单个聊天完成请求。非常适合作为起点。
```bash
OPENAI_API_KEY=sk-... go run ./basic
```
### streaming
通过 `gw.RouteStream()` 流式传输聊天完成 token。token 在收到时立即打印，而不是等待完整响应。
```bash
OPENAI_API_KEY=sk-... go run ./streaming
```
### custom-plugin
演示如何编写 `plugin.Plugin` 实现（请求 ID 注入器）并在 `before_request` 阶段注册它。
```bash
OPENAI_API_KEY=sk-... go run ./custom-plugin
```
### embedded
展示如何将网关作为 HTTP 处理程序嵌入到您自己的 `net/http` 服务器中，将 AI 路由与现有应用程序路由一起挂载。
```bash
OPENAI_API_KEY=sk-... go run ./embedded
# 然后：curl -X POST http://localhost:8080/ai/v1/chat/completions -d '...'
```
### fallback
配置 `ModeFallback`：网关按顺序尝试提供者，在主提供者重试后切换到下一个提供者。需要至少一个提供者密钥；建议使用两个提供者。
```bash
OPENAI_API_KEY=sk-... ANTHROPIC_API_KEY=sk-ant-... go run ./fallback
```
### loadbalance
配置 `ModeLoadBalance` 并使用加权目标。第一个提供者接收 70% 的请求，其余提供者共享剩余的 30%。需要至少两个提供者密钥。
```bash
OPENAI_API_KEY=sk-... ANTHROPIC_API_KEY=sk-ant-... go run ./loadbalance
```
### with-circuit-breaker
将 `CircuitBreakerConfig` 附加到主提供者目标。连续两次失败后，断路器打开 10 秒，所有流量路由到备用提供者。
```bash
OPENAI_API_KEY=sk-... ANTHROPIC_API_KEY=sk-ant-... go run ./with-circuit-breaker
```
### with-guardrails
通过 `PluginConfig` 加载内置的 `word-filter` 和 `max-token` 防护插件。包含被阻止的单词的请求在到达提供者之前被拒绝。
```bash
OPENAI_API_KEY=sk-... go run ./with-guardrails
```
### with-hooks
通过 `gw.AddHook(fn)` 注册事件钩子。钩子在每次请求后异步接收 `gateway.request.completed` 和 `gateway.request.failed` 事件 — 可用于遥测、成本跟踪或审计日志。
```bash
OPENAI_API_KEY=sk-... go run ./with-hooks
```
### with-mcp
启动本地模拟 MCP 服务器，将其连接到网关，并发送工具调用请求。网关注入工具定义，驱动代理工具调用循环，并返回最终答案。
```bash
OPENAI_API_KEY=sk-... go run ./with-mcp
# 最适合支持工具/函数调用的模型（gpt-4o、claude-3-5-sonnet 等）
```
## 支持的提供者环境变量
| 变量 | 提供者 |
|----------|----------|
| `OPENAI_API_KEY` | OpenAI |
| `ANTHROPIC_API_KEY` | Anthropic |
| `GROQ_API_KEY` | Groq |
| `GEMINI_API_KEY` | Google Gemini |
| `MISTRAL_API_KEY` | Mistral |
| `TOGETHER_API_KEY` | Together AI |
| `COHERE_API_KEY` | Cohere |
| `DEEPSEEK_API_KEY` | DeepSeek |
## 更多信息
- [AI 网关仓库](https://github.com/ferro-labs/ai-gateway)
- [文档](https://github.com/ferro-labs/ferrolabs-docs)
