> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# 概览

Alephant 是面向生产级智能体和工作流的智能体财务网关。AI Gateway 是该平台中的模型访问层：它为智能体提供统一可靠的模型调用方式，同时 Alephant 围绕完整的智能体运行实施路由、策略、追踪、成本归因和财务控制。

团队无需将每个智能体或应用直接对接每一家提供商，只需连接一次，即可路由至 50+ 家提供商、320+ 个模型及自定义模型后端。可使用 Alephant Cloud 获取托管工作区；当需要私有基础设施、自带密钥（BYO keys）和直接运维控制时，也可自行托管网关。

OpenAI 兼容性是入口，而非产品边界。请求仍可采用标准的 `/v1/chat/completions` 调用形式，但 Alephant 可以将其关联到 Agent ID、Run ID、会话、策略决策、预算、缓存事件、请求日志、支付事件和利润记录。

```typescript
import { OpenAI } from "openai";

const client = new OpenAI({
  baseURL: "https://ai.alephant.io/v1",
  apiKey: process.env.ALEPHANT_VIRTUAL_KEY,
  defaultHeaders: {
    "Alephant-Agent-Id": "agt_support_bot_8f3a",
    "Alephant-Run-Id": "run_demo_001",
    "alephant-session-id": "session-xxx", // optional
  },
});

const response = await client.chat.completions.create({
  model: "openai/gpt-4o-mini",
  messages: [{ role: "user", content: "Hello!" }]
});
```

## **为何需要它**

AI 应用正从单模型原型转向调用模型、工具、API 和付费端点的智能体与工作流。没有网关时，每个团队都不得不重复构建相同的运维层：提供商适配器、路由规则、密钥管理、使用元数据、重试、缓存和请求日志。

Alephant AI Gateway 通过一个开发者友好的 API 集中管理模型访问，并将每个请求连接到更广泛的 Alephant 控制平面。开发者可继续使用熟悉的 SDK 集成；平台和财务团队则可在访问提供商前执行策略、在发生事故前获得可追踪性、在预算审查前完成成本归因，并在智能体能力作为付费端点出售时获得收入可见性。

目标很简单：在不拖慢开发者的前提下，让智能体活动可观测、可治理、可靠且具备财务责任归属。[*了解更多 ->*](https://alephant.io/)

## **功能**

| **能力**    | **Alephant 提供的内容**                                                             |
| --------- | ------------------------------------------------------------------------------ |
| 智能体感知网关   | 兼容 OpenAI 的 `/v1/*` 和 `/ai/*` 路由，可将流量关联到智能体、Run ID、会话、Virtual Key、部门和工作区       |
| 提供商和模型覆盖  | 50+ 家提供商、320+ 个模型、本地运行时、OpenRouter 风格目录以及自定义/私有后端                              |
| 提供商适配     | 跨提供商 API 的请求、工具、流式响应、错误、用量、结束原因和响应标准化                                          |
| 路由与弹性     | 直接提供商路径、策略路由器、重试、回退、健康检查、提供商 429 处理和故障开放缓存路径                                   |
| 智能体客户端兼容性 | 面向 Cursor、Codex、opencode、Antigravity、n8n、MCP 和现有 OpenAI SDK 工作流的 OpenAI 兼容格式   |
| 策略和密钥控制   | Virtual Key、主密钥解析、模型策略、工作区提供商允许列表、预算、速率限制和并发控制                                 |
| 缓存        | 网关侧 LLM KV 缓存和语义缓存，避免重复上游调用                                                    |
| 运行可观测性    | 请求日志、追踪、会话、Agent ID、Run ID、用量元数据、策略事件、可选请求体归档和下游日志投递                           |
| 智能体财务     | Token 成本、外部工具/API 支出、出站支付支出、端点收入、缓存节省和已知利润归因                                   |
| 商业化路径     | 通过 x402 和 MPP 支付通道对外提供受治理的付费端点                                                 |
| 在线运维      | 无需重启网关，即可根据数据库变更刷新路由、Virtual Key 和提供商密钥                                        |
| 部署        | 通过 Alephant Cloud 提供托管 SaaS，或使用 PostgreSQL、Redis、Qdrant 和兼容 S3 的集成自行托管 Rust 网关 |

## **开发者接口**

| **接口**                    | **用途**                                                     |
| ------------------------- | ---------------------------------------------------------- |
| `/v1/*`                   | 可直接替换现有 OpenAI SDK 和智能体客户端的模型 API                          |
| `/router/{id}/*`          | 经由已配置路由器进行策略驱动的路由                                          |
| `/{provider}/*`           | 当需要明确控制上游时，直接透传至提供商                                        |
| `model=provider/model_id` | 无需修改应用代码即可选择提供商和模型                                         |
| 智能体/运行请求头                 | 将 `Alephant-Agent-Id`、`Alephant-Run-Id`、会话、请求和自定义属性关联到模型流量 |
| 自定义后端                     | 将私有模型或自行托管的运行时置于同一网关合同之后                                   |

## **架构与请求生命周期**

每个请求都经过相同的网关生命周期：身份验证、智能体上下文、策略检查、路由、提供商映射、分发、缓存、回退和异步日志。入口路径取决于所需的控制程度：

| **路径**           | **适用场景**                                       |
| ---------------- | ---------------------------------------------- |
| `/v1/*`          | 使用 `model=provider/model_id` 进行统一的 OpenAI 风格访问 |
| `/router/{id}/*` | 经由已配置路由器进行策略驱动的路由                              |
| `/{provider}/*`  | 需要明确上游时直接透传至提供商                                |

## **多提供商适配**

可在 50+ 家提供商和 320+ 个模型中使用一种熟悉的请求格式，包括 OpenAI 兼容 API、Anthropic Messages、Gemini、Bedrock、Ollama、OpenRouter 风格目录和自定义后端。客户端通过 `model=provider/model_id` 选择运行时；Alephant 会解析提供商、应用正确的适配器、映射提供商特有字段，并返回标准化响应。

本节不在 README 中逐一列出所有模型，而是聚焦于合同：一种请求格式输入，一致的响应格式输出。提供商和模型目录可以独立演进，无需强制修改应用代码。

|               |                                                                                                                                                                         |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **主流模型**      | GPT-4o · GPT-4.1 · o3 · Claude 3.5/3.7 Sonnet · Claude Opus · Gemini 1.5/2.0 · Llama 3/4 · Mistral Large · Command R+                                                   |
| **提供商生态**     | OpenAI · Anthropic · Google Gemini · AWS Bedrock · Azure OpenAI · OpenRouter · Together AI · Fireworks · Groq · Cohere · Mistral · Perplexity · DeepSeek · xAI · Ollama |
| **智能体客户端兼容性** | Cursor · Codex · opencode · Antigravity                                                                                                                                 |

## **IDE 集成**

Alephant AI Gateway 为受支持 IDE 中的 AI 辅助开发提供仓库级工具。

| **IDE / 智能体客户端** | **状态** | **包含内容**                                                                                                          |
| ---------------- | ------ | ----------------------------------------------------------------------------------------------------------------- |
| Cursor           | 已就绪    | 项目架构与代码规范规则、开发和 API 工作流指南、受控模块实现技能（Skill）、基于文件的任务管理（Task Magic）——见 `.cursor` 目录；也可在 Agent Settings → Models 中配置网关 |
| opencode         | 进行中    | 适配器和配置正在开发                                                                                                        |
| Codex            | 进行中    | 适配器和配置正在开发                                                                                                        |
| Claude Code      | 进行中    | 适配器和配置正在开发                                                                                                        |

## **对比**

Portkey、Helicone 和 LiteLLM 都是优秀项目，但它们的重心不同。Alephant 面向交付智能体 AI 产品的团队构建：提供托管 SaaS 工作区和自行托管网关路径，用于智能体治理、运行追踪、模型路由、成本控制和智能体商业化。

| **项目**              | **最为人所知的能力**                       | **最适合**                                        |
| ------------------- | ---------------------------------- | ---------------------------------------------- |
| Portkey             | 企业级 AI 网关控制、护栏和托管策略工作流             | 希望获得托管 AI 控制平面的团队                              |
| Helicone            | LLM 可观测性、请求分析、会话和成本可见性             | 主要需求是追踪和分析的团队                                  |
| LiteLLM             | 面向众多提供商的广泛 Python 代理/SDK 生态        | 希望通过 Python 技术栈获得最广提供商覆盖的团队                    |
| Alephant AI Gateway | 智能体财务、治理、运行追踪、提供商路由以及 SaaS + 自托管部署 | 构建生产级智能体且需要成本护栏、运行可追踪性、BYO keys、付费端点和多提供商控制的团队 |

| **能力**        | **Portkey** | **Alephant**    | **LiteLLM**        | **Alephant AI Gateway**                  |
| ------------- | ----------- | --------------- | ------------------ | ---------------------------------------- |
| OpenAI 兼容 API | 是           | 是               | 是                  | 是                                        |
| SaaS + 自托管    | 企业版/自托管选项   | 托管和自托管选项        | 自托管代理              | 是：Alephant Cloud 加自行托管 Rust 网关           |
| 提供商/模型覆盖      | 广泛          | 广泛的日志/代理覆盖      | 非常广泛               | 50+ 家提供商、320+ 个模型、自定义后端                  |
| 智能体编码客户端      | 无专用兼容层      | 无专用兼容层          | 无专用兼容层             | Cursor、Codex、opencode、Antigravity 工作流    |
| 智能体财务         | 护栏和策略控制     | 成本分析和请求可见性      | 预算和支出控制            | 感知智能体/会话的用量可见性、缓存节省、外部支出、端点收入和利润归因       |
| 提供商适配         | 网关策略和路由     | 代理加可观测性管道       | 强大的提供商抽象           | 请求、流式响应、错误、用量和响应的显式映射器                   |
| 路由与弹性         | 路由、重试、回退    | 网关控制加可观测性       | 路由器、回退、预算          | 直接路径、策略路由器、回退、健康检查、提供商 429 处理            |
| BYO 密钥控制      | 密钥库/企业控制    | 带代理控制的 BYO keys | Virtual Key 和自托管密钥 | BYO 提供商密钥、主密钥解析、工作区允许列表                  |
| 缓存            | 网关缓存        | 缓存追踪/集成         | 缓存集成               | LLM KV 缓存加语义缓存                           |
| 可观测性          | 日志和策略事件     | 核心优势            | 回调/日志集成            | 日志、追踪、指标、用量元数据、可选请求体归档                   |
| 治理路径          | 强大的企业护栏     | 围绕可观测性的工作区控制    | 团队、预算、速率限制         | 智能体/运行治理、模型策略、提供商允许列表、付费端点规则、并发控制和工作区级控制 |

Alephant 的差异化在于这种组合：托管 SaaS、自行托管 Rust 网关、智能体优先的开发者兼容性、运行级治理、BYO 密钥控制、显式提供商适配、AI FinOps 和支付感知的商业化。

## **仓库结构**

```
alephant-ai-gateway/
├── ai-gateway/                 # Gateway service crate
├── crates/                     # Shared libraries and harnesses
├── docs/                       # In-repo notes; curated docs at https://api.alephant.io/
├── scripts/                    # CI and local automation
├── infrastructure/             # Deployment and observability infra
├── test/                       # Integration and runtime test helpers
├── AGENTS.md                   # Agent collaboration conventions
├── CLAUDE.md                   # Command and architecture reference
└── CHANGELOG.md                # Project changelog
```