> 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.

# 网关集成

> 配置 Virtual Key 并通过 Alephant 发送兼容提供商的请求

Alephant Gateway 是 Agentic Finance Gateway 的模型访问层。它让智能体、成员、工作流和应用程序通过 Alephant Virtual Key 路由 LLM 请求，而非暴露原始 provider key。请求保持与 provider 兼容，同时 Alephant 会应用身份验证、路由、日志记录、预算、策略检查、分析和智能体运行归属。

## 配置 Virtual Key

1. 在 **Keys** 中添加 provider key。这是 Alephant 安全存储的上游 provider 凭据。
2. 为将发送流量的应用程序、服务或用户创建 **Agent** 或 **Virtual Key**。
3. 使用要强制执行的 provider、model 访问、department、budget 和 policy 配置该密钥。
4. 复制生成的 `vk-...` token。此 token 是您的应用程序发送给 Alephant Gateway 的凭据。

请为不同的应用程序、环境、智能体或团队使用单独的 Virtual Key。这可使日志、成本归属和策略执行保持清晰。

## 通过网关发送请求

使用为您的环境配置的 Gateway 基础 URL，并在标准 `Authorization` 请求头中传递 Virtual Key。

```bash
curl https://alephant.io/v1/chat/completions \
  -H "Authorization: Bearer $ALEPHANT_VIRTUAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      { "role": "user", "content": "Write a one sentence status update." }
    ]
  }'
```

对于网关请求，请使用 Virtual Key。请勿将您的 provider API key 发送给 Alephant；网关会在验证 Virtual Key 后注入已配置的上游凭据。

## 必填请求头

| 请求头             | 用途                                                              |
| --------------- | --------------------------------------------------------------- |
| `Authorization` | 必需。使用 `Bearer <virtual-key>`。网关验证 Virtual Key 后，会在转发到上游前移除此请求头。 |
| `Content-Type`  | 对 JSON 模型请求使用 `application/json`。其他兼容 provider 的内容类型会被直接传递。     |

## 可选追踪请求头

这些请求头帮助您向请求附加业务上下文，并改进日志、分析和调试。标记为仅网关使用的请求头不会转发给上游模型 provider。

| 请求头                       | 用途                                                                                                      |
| ------------------------- | ------------------------------------------------------------------------------------------------------- |
| `x-request-id`            | 可选的请求关联 ID。如果存在且兼容 UUID，可作为请求日志 ID 和策略请求 ID 使用。缓存命中响应可能会使用响应中的 `alephant-id` 替代请求关联。                    |
| `Alephant-Agent-Id`       | 仅网关使用。用于智能体运行归属的稳定 Alephant agent ID。新的集成应优先使用此请求头。                                                     |
| `Alephant-Run-Id`         | 仅网关使用。一次任务执行的稳定 run ID。在同一 run 的所有模型或工具调用中复用。                                                           |
| `alephant-session-id`     | 仅网关使用。将请求归组到一个 session，以用于日志和分析。                                                                        |
| `alephant-session-path`   | 仅网关使用。可选的 session 路径。优先使用以 `/` 开头的值，例如 `/checkout/retry`。                                               |
| `alephant-session-name`   | 仅网关使用。可选的人类可读 session 名称。                                                                               |
| `alephant-property-*`     | 仅网关使用。自定义日志属性。例如 `alephant-property-environment: production` 或 `alephant-property-feature: onboarding`。 |
| `alephant-prompt-id`      | 仅网关使用。在转发请求前应用已存储的 prompt template。请求体必须是有效 JSON。                                                       |
| `alephant-forced-routing` | 高级功能。在 route 支持时强制路由到有效的 provider 名称。仅用于受控测试或显式故障转移 workflow。                                           |

请求追踪示例：

```bash
curl https://alephant.io/v1/chat/completions \
  -H "Authorization: Bearer $ALEPHANT_VIRTUAL_KEY" \
  -H "Content-Type: application/json" \
  -H "x-request-id: 018f7f83-2a7a-7f1a-9b2f-2f2b21e8a001" \
  -H "Alephant-Agent-Id: agt_support_bot_8f3a" \
  -H "Alephant-Run-Id: run_ticket_8421_20260609_001" \
  -H "alephant-session-id: onboarding-demo" \
  -H "alephant-property-environment: production" \
  -H "alephant-property-customer-tier: enterprise" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      { "role": "user", "content": "Summarize this customer ticket." }
    ]
  }'
```

有关 Agent ID、Run ID、Session ID、Request ID 和 Trace ID 的完整指南，请参阅 [智能体 ID 与运行 ID](/docs/overview/core-concepts/agent-i-ds-and-run-i-ds)。

## 缓存请求头

Alephant 支持网关侧响应缓存。缓存请求头为可选项，且不会发送给上游模型 provider。

| 请求头                              | 用途                               |
| -------------------------------- | -------------------------------- |
| `Alephant-Cache-Enabled`         | 设为 `true` 时启用缓存行为。               |
| `Alephant-Cache-Read`            | 设为 `true` 时允许从缓存读取。              |
| `Alephant-Cache-Save`            | 设为 `true` 时允许将响应保存到缓存。           |
| `Alephant-Cache-Bucket-Max-Size` | 可选的 bucket 数量。有效范围为 1-20。        |
| `Alephant-Cache-Seed`            | 可选 seed，参与缓存 key 派生。             |
| `Alephant-Cache-Control`         | 可选缓存控制，如 `max-age` 或 `s-maxage`。 |

语义缓存和 embedding 请求头是高级网关控制项。仅当您的 workspace 已配置语义缓存时使用它们：

| 请求头                                 | 用途                         |
| ----------------------------------- | -------------------------- |
| `Alephant-Embeddings-Model`         | 用于语义缓存查找的 embedding model。 |
| `Alephant-Embeddings-Key`           | 网关用于语义缓存查找的 embedding 凭据。  |
| `Alephant-Cache-Semantic-Threshold` | 语义缓存匹配的相似度阈值。              |
| `Alephant-Cache-Ttl`                | 语义缓存 TTL。                  |

## 日志与隐私控制

一些请求头会影响请求日志行为。

| 请求头                       | 用途                             |
| ------------------------- | ------------------------------ |
| `alephant-omit-request`   | 存在时省略请求侧日志行为。                  |
| `alephant-omit-response`  | 存在时省略响应侧日志行为。                  |
| `cf-ipcountry`            | 流量位于 Cloudflare 后方时的国家/地区代码来源。 |
| `x-alephant-country-code` | `cf-ipcountry` 缺失时的国家/地区代码后备值。 |
| `Referer`                 | 记录为请求来源页面。                     |

避免将密钥或受监管的个人数据放入自定义 `alephant-property-*` 请求头。它们旨在承载可安全显示在日志中的运营元数据。

## 客户端 IP 与策略评估

网关使用请求元数据评估策略，其中包括可表示为 UTF-8 的请求头。对于客户端 IP：

* 策略评估可能使用 `x-forwarded-for`，其中最左侧的 IP 被视为客户端 IP。
* 仅当直接对等端是已配置的受信任代理时，限流才信任 `x-forwarded-for`。否则，使用直接对等端 IP。

## 响应请求头

网关响应可能包含 Alephant 特有的响应元数据，例如：

| 请求头                         | 用途                          |
| --------------------------- | --------------------------- |
| `alephant-provider`         | 启用响应请求头时，由网关选择的 provider。   |
| `alephant-provider-req-id`  | 可用且已启用时的上游 provider 请求 ID。  |
| `alephant-cache`            | 启用缓存的请求的缓存状态。               |
| `alephant-cache-bucket-idx` | 缓存命中的 cache bucket 索引。      |
| `alephant-cache-latency`    | 缓存查找延迟。                     |
| `alephant-id`               | Alephant 请求标识符，尤其适用于缓存命中响应。 |

## 验证请求

通过网关发送请求后：

1. 打开 **Logs** 确认请求已被记录。
2. 在 **Analytics** 中检查支出、请求、token 用量、model、provider 和范围限定元数据。
3. 如果请求失败，请检查 HTTP 状态以及 Virtual Key 的 policy 或 budget 配置。

常见故障包括无效的 Virtual Key 身份验证、策略阻止、限流、不受支持的模型或预算强制执行。