概览核心概念

网关集成

以 Markdown 格式查看

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。

$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。

请求追踪示例：

$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。

缓存请求头

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-codecf-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-idAlephant 请求标识符，尤其适用于缓存命中响应。

验证请求

通过网关发送请求后：

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

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