# llm-gateway

**Repository Path**: oywb33/llm-gateway

## Basic Information

- **Project Name**: llm-gateway
- **Description**: # LLM Gateway

基于 Go 实现的轻量级 LLM 推理网关，提供 OpenAI 兼容的统一 API 入口，支持多提供商智能路由。
- **Primary Language**: Go
- **License**: BSD-3-Clause
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-11
- **Last Updated**: 2026-09-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LLM Gateway v2.0

基于 Go 实现的轻量级 LLM 推理网关 + Agent 执行引擎，提供 OpenAI 兼容的统一 API 入口，支持 **19 个平台、93 个模型**智能路由，并内置完整的 Agent 执行能力。

## 特性

### LLM 代理
- **统一入口** — `/v1/chat/completions` 端点，兼容 OpenAI SDK
- **多提供商** — 国内 10 家 + 国外 8 家 + Anthropic，共 19 个平台
- **智能路由** — 根据请求中的 `model` 自动匹配对应提供商
- **格式转换** — Anthropic 请求自动从 OpenAI 格式转换
- **流式支持** — 完整支持 SSE 流式响应
- **API 认证** — Bearer Token 或 `x-api-key` 认证
- **频率限制** — 基于 IP 的内存限流
- **优雅关闭** — SIGINT/SIGTERM 信号平滑退出

### Agent 执行引擎（v2.0 新增）
- **Agent 主循环** — 思考→规划→工具调用→观察的完整 Agent 循环
- **工具系统** — bash、read、write、edit、grep、find、ls 7 个标准工具
- **安全机制** — 多层审批（黑名单/白名单/交互审批）+ 五级命令风险分类
- **MCP 集成** — 真实 MCP 客户端，支持 stdio/HTTP/SSE 三种传输
- **子Agent 调度** — 并行/串行子Agent 执行，最大 100 轮迭代
- **流式事件** — SSE 实时推送 Agent 状态、工具执行、审批请求

## 支持的平台

### 国内平台

| 提供商 | 模型 | 注册地址 | 优势 | 方向 |
|--------|------|----------|------|------|
| 阿里百炼（通义千问） | qwen3-235b, qwen-max, qwen-plus 等 8 个 | [bailian.console.aliyun.com](https://bailian.console.aliyun.com) | 中文理解能力顶尖，多模态能力突出，阿里云生态整合 | 电商、金融、企业办公场景，多模态应用 |
| 火山方舟（豆包） | doubao-1.5-pro, deepseek-r1/v3 等 7 个 | [console.volcengine.com/ark](https://console.volcengine.com/ark) | 性价比极高，字节跳动生态深度整合，支持多模态 | 内容创作、社交娱乐、智能客服 |
| DeepSeek 官方 | deepseek-chat, deepseek-reasoner | [platform.deepseek.com](https://platform.deepseek.com) | 开源模型性能全球领先，推理能力极强，API 价格极低 | 编程辅助、数学推理、通用对话 |
| 智谱AI（GLM） | glm-4-plus, glm-4-flash 等 5 个 | [open.bigmodel.cn](https://open.bigmodel.cn) | 国产自研 GLM 架构，多模态理解，学术研究能力突出 | 学术研究、企业知识库、智能体应用 |
| 月之暗面（Kimi） | moonshot-v1, kimi-latest 等 4 个 | [platform.moonshot.cn](https://platform.moonshot.cn) | 超长上下文（200万 token），文件处理能力业界领先 | 长文档分析、论文阅读、合同审查 |
| 百度千帆（文心） | ernie-4.5, ernie-4.0-turbo 等 4 个 | [console.bce.baidu.com/qianfan](https://console.bce.baidu.com/qianfan) | 中文理解深厚，搜索增强能力，百度生态整合 | 搜索增强、知识问答、企业应用 |
| 零一万物（Yi） | yi-large, yi-lightning 等 4 个 | [platform.lingyiwanwu.com](https://platform.lingyiwanwu.com) | 开源模型性能优秀，中英双语均衡，训练效率高 | 通用对话、内容生成、开源社区 |
| 硅基流动 | Qwen2.5-72B, DeepSeek-V3/R1 等 8 个 | [siliconflow.cn](https://siliconflow.cn) | 多模型聚合平台，推理成本低，一键部署开源模型 | 模型评测对比、低成本推理、开源模型服务 |
| 腾讯混元 | hunyuan-turbo, hunyuan-large 等 5 个 | [console.cloud.tencent.com/hunyuan](https://console.cloud.tencent.com/hunyuan) | 腾讯生态深度整合，微信/企微场景优化，多模态能力 | 社交应用、游戏、企业微信场景 |
| 讯飞星火 | 4.0Ultra, generalv3.5 等 4 个 | [xinghuo.xfyun.cn](https://xinghuo.xfyun.cn) | 语音识别/合成技术结合，教育场景深耕 | 教育、语音交互、智能硬件 |

### 国外平台

| 提供商 | 模型 | 注册地址 | 优势 | 方向 |
|--------|------|----------|------|------|
| OpenAI | gpt-4.1, gpt-4o, o4-mini, o3-mini 等 6 个 | [platform.openai.com](https://platform.openai.com) | 行业标杆，多模态能力领先，生态最完善，SDK 支持最广 | 通用对话、代码生成、多模态理解、Agent 开发 |
| Google Gemini | gemini-2.5-flash/pro, gemini-2.0-flash 等 4 个 | [aistudio.google.com](https://aistudio.google.com) | 多模态原生设计，100 万 token 超长上下文，Google 生态整合 | 多模态分析、长文档处理、搜索增强 |
| Anthropic Claude | claude-sonnet-4, claude-3.5-sonnet 等 4 个 | [console.anthropic.com](https://console.anthropic.com) | 安全性/对齐能力业界领先，代码生成能力极强，长上下文 | 代码开发、安全合规、长文档分析 |
| Mistral AI | mistral-large, pixtral-large, codestral 等 5 个 | [console.mistral.ai](https://console.mistral.ai) | 欧洲领先 AI 厂商，开源模型优秀，多语言支持好 | 多语言应用、企业部署、开源社区 |
| Groq | llama-3.3-70b, mixtral-8x7b 等 5 个 | [console.groq.com](https://console.groq.com) | 自研 LPU 推理芯片，推理速度极快（数百 token/秒），免费额度 | 实时对话、高速推理、原型验证 |
| Together AI | Llama-3.3-70B, DeepSeek-V3/R1 等 6 个 | [together.ai](https://www.together.ai) | 开源模型推理平台，支持模型微调，性价比高 | 模型微调、开源模型推理、A/B 测试 |
| Perplexity | sonar-pro, sonar-reasoning 等 4 个 | [perplexity.ai](https://www.perplexity.ai) | 搜索增强 AI，实时信息检索，回答可溯源引用 | 研究调研、实时信息查询、事实核查 |
| xAI (Grok) | grok-3, grok-3-mini, grok-2 等 4 个 | [x.ai](https://x.ai) | 实时信息获取，X 平台数据整合，推理能力强 | 社交媒体分析、实时趋势、创意写作 |
| Cohere | command-r-plus, command-a 等 4 个 | [dashboard.cohere.com](https://dashboard.cohere.com) | 企业级 RAG 方案，多语言嵌入模型领先，命令行工具成熟 | 企业 RAG、语义搜索、多语言嵌入 |

## 快速开始

### 编译

```bash
cd llm-gateway
go build -o llm-gateway.exe .
```

### 配置 API Key

```powershell
# PowerShell
$env:OPENAI_API_KEY = "sk-xxx"
$env:ARK_API_KEY = "your-ark-api-key"
$env:BAILIAN_API_KEY = "sk-xxx"
# ... 按需设置其他环境变量
```

```bash
# Linux / macOS
export OPENAI_API_KEY="sk-xxx"
export ARK_API_KEY="your-ark-api-key"
```

### 启动

```bash
./llm-gateway -config config.yaml
```

## API 端点

### LLM 代理

| 端点 | 方法 | 认证 | 说明 |
|------|------|------|------|
| `/health` | GET | 无 | 健康检查（含版本和功能列表） |
| `/v1/models` | GET | 无 | 模型列表 |
| `/v1/chat/completions` | POST | 需要 | 对话补全（支持流式） |

### Agent 执行（v2.0 新增）

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/v1/agent/run` | POST | 非流式 Agent 执行 |
| `/api/v1/agent/run/stream` | POST | SSE 流式 Agent 执行 |
| `/api/v1/agent/approve` | POST | 审批危险操作 |
| `/api/v1/agent/abort` | POST | 中止 Agent 执行 |

### MCP 管理（v2.0 新增）

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/v1/mcp/servers` | GET | 列出已连接的 MCP Server |
| `/api/v1/mcp/servers` | POST | 添加 MCP Server |
| `/api/v1/mcp/servers` | DELETE | 移除 MCP Server |
| `/api/v1/mcp/tools` | GET | 列出 MCP Server 的工具 |
| `/api/v1/mcp/tools/call` | POST | 调用 MCP 工具 |

### 工具（v2.0 新增）

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/v1/tools/classify` | POST | 命令风险分类 |

### 调用示例

```bash
# 健康检查
curl http://localhost:8080/health

# 查看可用模型
curl http://localhost:8080/v1/models

# 非流式请求
curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer sk-gateway-demo-key-001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-1.5-pro-32k",
    "messages": [{"role": "user", "content": "你好"}]
  }'

# 流式请求
curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer sk-gateway-demo-key-001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "你好"}],
    "stream": true
  }'

# Agent 执行（流式）
curl http://localhost:8080/api/v1/agent/run/stream \
  -H "Content-Type: application/json" \
  -d '{
    "message": "列出当前目录的文件",
    "mode": "agent",
    "work_dir": "."
  }'

# 命令风险分类
curl http://localhost:8080/api/v1/tools/classify \
  -H "Content-Type: application/json" \
  -d '{"command": "rm -rf /"}'
```

PowerShell 调用示例：

```powershell
$headers = @{
  "Authorization" = "Bearer sk-gateway-demo-key-001"
  "Content-Type" = "application/json"
}
$body = '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"你好"}]}'
Invoke-WebRequest -Uri "http://localhost:8080/v1/chat/completions" `
  -Method POST -Headers $headers -Body $body
```

## 配置说明

`config.yaml` 结构：

```yaml
server:
  port: 8080              # 监听端口
  read_timeout: 120s      # 读取超时
  write_timeout: 120s     # 写入超时

auth:
  enabled: true           # 是否启用认证
  api_keys:               # 网关 API Key 列表
    - "sk-gateway-demo-key-001"

providers:
  - name: "bailian"       # 提供商名称
    type: "openai"        # 类型: openai / anthropic
    base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
    api_key: "${BAILIAN_API_KEY}"  # 支持环境变量 ${VAR}
    models:               # 该提供商支持的模型列表
      - "qwen-max"
      - "qwen-plus"
    default: true         # 是否为默认提供商（未匹配模型时回退）

# Agent 配置（v2.0 新增）
agent:
  max_iterations: 100          # 最大迭代轮数
  max_tool_concurrency: 10     # 最大并发工具调用
  tool_execution_mode: parallel # 工具执行模式: sequential / parallel
  sandbox_enabled: false       # 是否启用沙箱（Linux 需要 bwrap）

rate_limit:
  enabled: true
  requests_per_minute: 60
```

## 路由逻辑

1. 解析请求中的 `model` 字段
2. 在所有提供商中查找匹配的模型
3. 匹配成功 → 转发到对应提供商
4. 匹配失败 → 回退到 `default: true` 的提供商
5. 无默认提供商 → 返回 400 错误

## Agent 工作模式

| 模式 | 说明 | 权限 |
|------|------|------|
| `plan` | 只读审核模式 | read/grep/find/ls 自动执行 |
| `agent` | 标准 Agent 模式 | write/edit/bash 需审批，read 自动执行 |
| `yolo` | 全自动模式 | 所有工具自动执行，无需审批 |
| `os` | 系统命令模式 | 仅 bash 工具可用，自动执行 |

## 命令风险等级

| 风险等级 | 说明 | 示例 |
|----------|------|------|
| `none` | 无风险（只读/信息查询） | `ls`, `pwd`, `git status`, `go version` |
| `low` | 低风险（文件创建） | `mkdir`, `touch`, `echo`, `cp` |
| `medium` | 中风险（文件删除/网络操作） | `rm`, `curl`, `pip install`, `git push` |
| `high` | 高风险（系统修改/提权） | `sudo`, `rm -rf`, `chmod 777`, `curl \| bash` |
| `critical` | 严重风险（系统破坏） | `rm -rf /`, `mkfs`, `shutdown`, `dd if=/dev/zero` |

## 项目结构

```
llm-gateway/
├── main.go                  # 入口，启动与优雅关闭
├── config.yaml              # 配置文件
├── config/config.go         # 配置加载与模型路由
├── provider/
│   ├── provider.go          # Provider 接口定义
│   ├── openai.go            # OpenAI 兼容实现
│   └── anthropic.go         # Anthropic 实现（含格式转换）
├── middleware/auth.go        # 认证 + 限流
├── handler/
│   ├── proxy.go             # 代理转发（流式/非流式）
│   ├── aigc.go              # AIGC 代理（文生图/视频/语音/数字人）
│   └── agent_handler.go     # Agent API 处理器
├── router/router.go         # 路由注册
├── agent/                    # Agent 核心引擎（v2.0 新增）
│   ├── types.go             # 事件系统（30+ 事件类型）、消息类型
│   ├── agent.go             # Agent 主循环（思考→工具→观察）
│   ├── system_prompt.go     # 多模式系统提示词构建
│   └── approval.go          # 多层审批机制
├── tools/                    # 工具执行系统（v2.0 新增）
│   ├── registry.go          # 工具注册表
│   ├── bash.go              # Shell 命令执行
│   ├── read.go              # 文件读取
│   ├── write.go             # 原子性文件写入
│   ├── edit.go              # 精确搜索替换编辑
│   ├── grep.go              # 纯 Go 正则搜索
│   ├── find.go              # 文件名模式搜索
│   └── ls.go                # 目录列表
├── agentruntime/
│   └── tool_policy.go       # 五级命令风险分类
├── mcp/
│   └── client.go            # MCP 客户端（stdio/HTTP/SSE）
└── cmd/verify/
    └── main.go              # 功能验证测试脚本
```

## 验证测试

运行功能验证测试（需要先启动网关）：

```bash
# 启动网关
./llm-gateway -config config.yaml

# 运行测试（另一个终端）
cd cmd/verify
go build -o verify_test.exe .
./verify_test.exe
```

测试覆盖 10 项：
1. 健康检查（版本和功能列表）
2. 模型列表
3. 命令风险分类（5 种风险等级）
4. Agent 非流式执行
5. Agent 流式执行（SSE）
6. MCP Server 管理（增删查）
7. Agent 审批
8. Agent 中止
9. LLM 代理转发
10. CORS 配置