modelgate (Mazori AI)

ModelGate

🚀 Open Source LLM Gateway & MCP Server with Policy Enforcement, Semantic Tool Search & Intelligent Routing

Why ModelGate • Features • MCP Gateway • Quick Start • Docker • API • Contributing

______________________________________________________________________

类似于Kong或Envoy，但专为LLM而设计 -适用于所有提供商的统一API、内置安全性、带语义工具发现的MCP网关和智能路由。

______________________________________________________________________

关键差异

🔐 RBAC第一架构

ModelGate采用 基于角色的访问控制是其核心，而不是事后补上。每个API请求都流经一个全面的策略引擎，该引擎强制执行7种现成的策略类型：提示安全、工具访问、速率限制、模型限制、MCP策略、语义缓存规则和预算控制。创建角色、分配策略，并使用精确的权限颁发API密钥，而无需编写自定义中间件。

🔌 支持本地模型的真正多提供商

超越云提供商。ModelGate本机支持 Ollama和其他本地模型服务器 与OpenAI、Anthropic、Google Gemini、AWS Bedrock、Azure OpenAI、Groq、Mistral、Together AI和Cohere。在本地模型上运行成本敏感的工作负载，在气隙基础设施上运行敏感数据，在边界模型上运行复杂推理——所有这些都通过一个具有自动提供程序密钥轮换和负载平衡的统一API。

🔌 带工具编排的MCP网关

ModelGate实现了一个完整的 模型上下文协议（MCP）网关 它充当人工智能代理工具的统一中心。与静态工具定义不同，MCP服务器可以在运行时注册工具，使AI代理能够在不更改代码的情况下发现新功能。网关处理：

• 工具注册 --连接任何符合MCP标准的服务器（文件系统、数据库、API、自定义工具）
• 许可执行 --基于角色的工具访问控制（允许、拒绝、需要批准）
• 执行日志记录 --每次工具调用的完整审计跟踪
• 多服务器支持 --将多个MCP服务器中的工具聚合到单个端点中

🔎 语义工具搜索(search_tools)

在数百个工具中找到合适的工具不需要精确的名称匹配。ModelGate提供了一个内置 search_tools AI代理可以调用的函数，使用自然语言发现相关工具：

{
  "name": "search_tools",
  "arguments": {
    "query": "something to read files from disk",
    "limit": 5
  }
}

这 search_tools 工具用途 向量嵌入 （通过Ollama或OpenAI）在所有注册的工具中执行语义相似性搜索。请求“发送电子邮件的东西”并查找 send_email, compose_message，或 notify_user--即使你不知道确切的工具名称。这使得AI代理能够：

• 自我发现能力 在运行时没有硬编码的工具列表
• 查找类似工具 当主工具不可用时
• 探索可用工具 基于任务描述

💾 语义响应缓存

通过以下方式降低成本和延迟 智能高速缓存 它理解意义，而不仅仅是精确匹配。即使措辞不同，类似的提示也会进入缓存，大大降低了重复工作负载的API成本。可配置的相似性阈值使您能够平衡缓存命中率和响应准确性。

🛡️ 内置快速安全

通过以下方式保护您的LLM应用程序 先进的快速注射检测 使用模糊模式匹配、同形符号规范化和同义词扩展。检测并阻止PII，应用内容过滤，并维护全面的审计日志——所有这些都可以根据角色进行配置。

______________________________________________________________________

特性

🔌 多提供商支持

• 开放人工智能 -GPT-5.2、GPT-5.2微米、GPT-5.2-纳米、O3、O4迷你、嵌入物
• Anthropic -克劳德4.5作品集，克劳德4.5十四行诗，克劳德4.5俳句
• 谷歌双子座 -Gemini 2.5 Pro、Gemini 2.5 Flash、Gemini 2.0 Flash
• AWS基岩 -克劳德（十四行诗，俳句），新星Pro/Lite/Micro，《骆驼3》，米斯特拉尔
• Azure OpenAI -所有Azure托管的OpenAI模型
• 奥拉玛 -本地型号（Llama 3.2、Qwen 3、Mistral等）
• 格罗克 -Llama，具有超低延迟的混音
• 米斯特拉尔AI -西北风大、中、小
• 携手AI，Cohere -各种开源模型

🚀 OpenAI兼容的API

为OpenAI API提供完全流媒体支持的Drop-in替换。与任何OpenAI SDK一起使用。

🔧 MCP网关和语义工具搜索

• 用于AI代理工具编排的完整MCP服务器实现
• 内建 search_tools 语义工具发现功能
• 连接多个MCP服务器（文件系统、数据库、API）
• 基于角色的工具权限（允许、拒绝、需要批准）
• 基于向量嵌入的自动工具索引

💾 语义缓存

通过基于语义相似性的智能响应缓存降低成本和延迟。

🔐 细粒度访问控制

• 基于角色的访问控制（RBAC）
• API密钥管理
• 7种策略类型（安全、速率限制、模型访问、预算等）

📊 综合可观察性

• 请求包含完整详细信息的日志
• 按供应商/型号进行成本跟踪
• 用于AI代理活动的代理仪表板
• 普罗米修斯指标
• 审核跟踪

企业功能（在企业版中可用）

• 智能路由（成本/延迟优化）
• 弹性模式（重试、断路器、回退）
• 多租户隔离
• 高级预算控制

______________________________________________________________________

快速开始

先决条件

使用Docker？ 所有依赖项（PostgreSQL、pgvector、Ollama、nomic嵌入文本）都会自动设置为 make compose-up.跳到 .

安装Ollama

语义特征（工具搜索、语义缓存）需要Ollama。它在本地运行，并通过 nomic-embed-text 模型。

macOS

# Install Ollama
brew install ollama

# Start Ollama service
ollama serve &

# Pull the embedding model
ollama pull nomic-embed-text

Linux

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Start Ollama service
systemctl start ollama
# Or run directly: ollama serve &

# Pull the embedding model
ollama pull nomic-embed-text

Docker (Automatic)

使用时 make compose-up，Ollama会自动启动并拉取嵌入模型：

# From docker-compose.yml
ollama:
  image: ollama/ollama:latest
  
ollama-init:
  command: ollama pull nomic-embed-text  # Auto-pulls model

使用Docker Compose时不需要手动设置。

Windows

从下载并安装 ollama.com/下载

然后在PowerShell中：

ollama pull nomic-embed-text

安装pgvector

pgvector是PostgreSQL的一个扩展，它支持向量相似性搜索，由ModelGate用于语义缓存。没有pgvector，语义缓存将退回到精确匹配缓存。

macOS (Homebrew)

# Install PostgreSQL with pgvector
brew install postgresql@16 pgvector

# Start PostgreSQL
brew services start postgresql@16

# Enable extension in your database
psql -d modelgate -c "CREATE EXTENSION IF NOT EXISTS vector;"

Ubuntu/Debian

# Add PostgreSQL APT repository (if not already added)
sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
sudo apt update

# Install PostgreSQL and pgvector
sudo apt install postgresql-16 postgresql-16-pgvector

# Enable extension
sudo -u postgres psql -d modelgate -c "CREATE EXTENSION IF NOT EXISTS vector;"

Docker (Automatic)

Docker Compose设置使用 ankane/pgvector 预装了pgvector的镜像：

# From docker-compose.yml
postgres:
  image: ankane/pgvector:latest  # pgvector included

使用Docker时不需要手动设置。

From Source

# Clone pgvector
git clone --branch v0.7.0 https://github.com/pgvector/pgvector.git
cd pgvector

# Build and install (requires PostgreSQL dev headers)
make
sudo make install

# Enable extension
psql -d modelgate -c "CREATE EXTENSION IF NOT EXISTS vector;"

Verify Installation

# Check if pgvector is available
psql -d modelgate -c "SELECT * FROM pg_available_extensions WHERE name = 'vector';"

# Check if extension is enabled
psql -d modelgate -c "SELECT extname, extversion FROM pg_extension WHERE extname = 'vector';"

预期产量：

 extname | extversion 
---------+------------
 vector  | 0.7.0

______________________________________________________________________

选项1:Docker（推荐）

# Clone repository
git clone https://github.com/mazori-ai/modelgate.git
cd modelgate

# Copy environment config
cp .env.example .env

# Start services (with local Ollama for embeddings)
docker-compose --profile with-ollama up -d

# Or without Ollama (use OpenAI embeddings)
docker-compose up -d

访问仪表板 http://localhost:8080

默认登录： admin@modelgate.local / admin123

选项2：手动安装

# 1. Install PostgreSQL with pgvector
# macOS
brew install postgresql@16 pgvector

# Ubuntu/Debian
sudo apt install postgresql-16 postgresql-16-pgvector

# 2. Create database
createdb modelgate
psql modelgate -c "CREATE EXTENSION IF NOT EXISTS vector;"

# 3. Clone and build
git clone https://github.com/mazori-ai/modelgate.git
cd modelgate
make build

# 4. Start the server (auto-applies schema)
./bin/modelgate

# Web UI is automatically served at http://localhost:8080
# For frontend development with hot-reload:
cd web && pnpm install && pnpm run dev

______________________________________________________________________

Docker部署

生产部署

# 1. Configure environment
cp .env.example .env
vim .env  # Edit with your settings

# 2. Build and start
docker-compose build
docker-compose up -d

# 3. View logs
docker-compose logs -f modelgate

环境变量

Docker编写配置文件

# Standard (no local embeddings)
docker-compose up -d

# With Ollama for local embeddings
docker-compose --profile with-ollama up -d

______________________________________________________________________

API使用

ModelGate提供了一个 兼容OpenAI的API 在端口8080上。

聊天补全

curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer mg-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4-20250514",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

流媒体

curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer mg-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Write a poem"}],
    "stream": true
  }'

使用模型别名

# Use aliases defined in config.toml
curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer mg-your-api-key" \
  -d '{"model": "claude", "messages": [...]}'  # → claude-sonnet-4

嵌入

curl http://localhost:8080/v1/embeddings \
  -H "Authorization: Bearer mg-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": "Hello world"
  }'

列出型号

curl http://localhost:8080/v1/models \
  -H "Authorization: Bearer mg-your-api-key"

使用MCP调用工具

# AI agent can discover and use tools dynamically
curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer mg-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude",
    "messages": [{"role": "user", "content": "Find tools that can help me read files"}],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "search_tools",
          "description": "Search for available tools by description",
          "parameters": {
            "type": "object",
            "properties": {
              "query": {"type": "string", "description": "Natural language description of what you need"},
              "limit": {"type": "integer", "description": "Max results to return"}
            },
            "required": ["query"]
          }
        }
      }
    ]
  }'

Python SDK示例

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="mg-your-api-key"
)

response = client.chat.completions.create(
    model="claude",  # Uses alias
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)

______________________________________________________________________

配置

config.toml

配置文件包含 仅限服务器设置提供程序API密钥和模型通过仪表板UI进行配置。

[server]
http_port = 8080          # Unified port (API + Web UI + GraphQL + MCP)
bind_address = "0.0.0.0"

[database]
driver = "postgres"
host = "localhost"
port = 5432
user = "postgres"
password = "postgres"
database = "modelgate"
ssl_mode = "disable"

[embedder]
type = "ollama"                      # or "openai" for cloud embeddings
base_url = "http://localhost:11434"
model = "nomic-embed-text"

[telemetry]
log_level = "info"                   # debug, info, warn, error

# Model aliases (optional) - map friendly names to full model IDs
[aliases]
claude = "anthropic/claude-sonnet-4-20250514"
gpt4 = "openai/gpt-4o"

提供商和模型设置

在中配置LLM提供程序 仪表板用户界面:

1. 提供商 → 为OpenAI、Anthropic、Bedrock等添加API密钥。
2. 模型 → 从提供程序刷新模型，根据需要启用/禁用
3. 角色 → 使用模型访问策略创建角色

______________________________________________________________________

策略类型

ModelGate支持7种用于精细控制的策略类型：

______________________________________________________________________

文档

______________________________________________________________________

发展

本地开发

# Full setup (installs tools + dependencies)
make setup

# Run backend in dev mode
make dev

# Run frontend dev server (separate terminal)
make web-dev

构建目标

# Build everything (backend + frontend)
make all

# Build only the Go binary
make modelgate

# Build only the frontend
make web

# Build Docker images
make docker-build

GraphQL代码生成

修改GraphQL架构时(internal/graphql/schema/*.graphql)，重新生成Go代码：

# Generate GraphQL resolvers and types
make graphql

# This generates code in:
#   - internal/graphql/generated/generated.go
#   - internal/graphql/model/models_gen.go

要手动安装gqlgen工具：

go install github.com/99designs/gqlgen@latest

测试

# Run all tests
make test

# Run tests with coverage report
make test-coverage

# Run linter
make lint

所有目标

make help    # Show all available targets

______________________________________________________________________

社区

• GitHub问题 --Bug报告和功能请求
• GitHub讨论 --问题和想法
• Discord 的中文翻译是“不和谐”或“纷争”。 --实时聊天和社区支持
• 推特 --更新和公告

贡献

我们欢迎捐款！请查看我们的 贡献指南 了解详情。

• 阅读 行为准则
• 检查 好的第一个问题 对于新来者
• 看 安全.md 用于报告漏洞

______________________________________________________________________

许可证

Apache许可证2.0——请参阅 许可证 了解详情。

______________________________________________________________________

Built with ❤️ by the ModelGate community info@mazori.ai