Agent 网关

护栏

以 Markdown 格式查看

护栏是 Alephant 流量周围的策略与执行框架，而不是单一过滤器或单条规则。它连接模型访问策略、Agent 专属策略、Session 成本控制、安全控制，以及用于解释每次决策的日志。

使用护栏可以定义工作区、部门、成员、Virtual Key、Agent 或 Session 能够访问什么以及可以花费多少。配置保存在 Alephant 控制平面中，由相关 Gateway 和后端运行时应用最终生效的策略。

护栏如何协同工作

策略入口主要作用域控制内容
LLM 策略工作区、部门、成员和 Virtual Key模型访问、预算、请求与 Token 限制、安全控制和路由行为
Agent 策略工作区、部门或单个 Agent 绑定允许的模型、Agent 预算、运行限制、重试行为、追踪要求和工具权限
Session 成本控制共享同一 session_id 的请求单 Session 预算、累计成本、突发保护、模型降级和 Agent 专属覆盖

护栏与 Endpoint Policy、Spend Policy 相互补充，但它们管理不同的运行时边界。Endpoint Policy 控制已发布的端点，Spend Policy 控制 Agent 对外支付。

LLM 策略

LLM 策略管理通过 Alephant Virtual Key 发起的调用。在 Dashboard 中打开 Control → LLM Policy，即可查看当前工作区、套餐和部署模式支持的控制项。

访问控制

访问控制决定哪些调用方和资源可以使用 Gateway：

  • Model Allowlist 将请求限制为已批准的模型。
  • IP/CIDR Allowlist 将 Gateway 访问限制为已批准的网络范围。
  • Department Key Access 控制哪些部门可以使用指定 Master Key。

模型和密钥访问范围应与工作负载保持一致。Fallback 或优化规则不能绕过访问限制。

用量限制

用量限制用于保护预算和上游容量：

  • 按月或按季度计算的工作区预算、告警阈值和超限动作
  • Daily Hard Stop 和 Monthly Spend Alert
  • RPM、RPH 和 Burst Allowance 等自定义请求限制
  • 并发请求限制和 Token 限制
  • 面向 Virtual Key 的成员预算上限
  • 部门级预算与速率覆盖

部分控制项始终启用，部分可以开启或关闭，另一些需要特定套餐。Dashboard 会显示当前状态和可用性，不应把所有列出的控制项都视为已经生效。

安全与合规

Enterprise 工作区可以提供更多控制：

  • 基于时间的访问窗口
  • 支持 block、redact 或 alert 行为的 PII 检测
  • 针对 API 请求与策略动作的审计日志

具体可用性取决于工作区套餐和部署模式。在生产环境依赖某项控制前，应先检查页面显示的策略状态。

智能路由与优化

与路由相关的护栏可以包括模型 Fallback、Semantic Caching、Provider Key 负载均衡和成本感知路由。这些控制还取决于已配置的路由模式、Managed Credits、Provider 访问，以及工作区使用 Managed Routing 还是仅使用 BYO Key。

不要因为某个路由选项可见就假设它已生效。请在 Dashboard 中检查状态，并参阅路由优化了解路由专属行为。

Agent 策略

Agent 策略用于定义可复用的策略配置，并将其绑定到工作区、部门或单个 Agent。在 Control → Agent Policy 中可以创建、编辑、启用、停用和绑定策略。

策略区域可配置值
模型访问所有模型、Provider 默认模型或选定模型
预算月度预算、单次运行最大成本，以及 alert 或 block 动作
运行时Runtime mode、是否要求 Run tracking、最大请求数、最长持续时间和重试次数
工具所有工具、选定工具或未配置
绑定工作区默认、部门、单个 Agent 或混合作用域

Agent 策略比通用的工作区控制目录更具体：它随 Agent 的运行生效，并提供用于归因和策略评估的 Agent 上下文。已配置字段表示期望的策略状态；该字段是否执行以及如何执行，仍以后端与 Gateway 运行态为准。

Session 成本控制

Session 成本控制管理共享同一 session_id 的一组相关模型调用。

控制项用途
C1 — Budget Cap设置单个 Session 允许的最大成本，并选择当前支持的拦截动作
C2 — Cost Accumulation跨调用累计成本，并为 Session 关联阈值动作
C3 — Rate Limiting防止 Session 出现失控循环和请求突发
C4 — Model Downgrade在接近成本阈值时，从一个已配置模型切换到更便宜的已配置模型
Per-Agent Overrides为选定 Agent 覆盖当前支持的工作区默认值

Dashboard 将预算上限拒绝描述为 HTTP 402，将速率限制拒绝描述为 HTTP 429。精确响应体和支持的拦截动作取决于已部署的 Gateway 版本，因此应用应处理 HTTP 状态并检查实际返回错误，而不是依赖未形成合同的错误字符串。

为每个请求附加 Session 和 Agent 上下文：

$curl "$ALEPHANT_GATEWAY_BASE_URL/chat/completions" \
>  -H "Authorization: Bearer $ALEPHANT_VIRTUAL_KEY" \
>  -H "Content-Type: application/json" \
>  -H "alephant-session-id: sess_support_8421" \
>  -H "Alephant-Agent-Id: agt_support_bot" \
>  -H "Alephant-Run-Id: run_support_8421_001" \
>  -d '{
>    "model": "openai/gpt-4o-mini",
>    "messages": [
>      { "role": "user", "content": "Classify this support request." }
>    ]
>  }'

将 ALEPHANT_GATEWAY_BASE_URL 设置为 Dashboard 中显示的 Gateway Base URL。Alephant Cloud 默认使用 https://ai.alephant.io/v1；private deployment 可以提供不同的运行时地址。

配置并验证策略

  1. 添加 Provider Key，并创建用于发送 Gateway 流量的 Virtual Key。
  2. 打开 Control → LLM Policy 或 Control → Agent Policy。
  3. 配置策略、作用域、状态以及当前支持的覆盖项。
  4. 通过已配置的 Gateway Base URL 发起请求，并在适用时携带 Agent、Run 和 Session 标识。
  5. 在 Request Logs 中检查实际 Provider、模型、状态、Token 用量、成本和策略元数据。
  6. 在 Sessions 中检查累计成本、拦截、模型变化和 Per-Agent 行为。
  7. 在 Audit Logs 中检查工作区暴露的配置和执行事件。

当多个作用域同时适用时，应在目标部署中验证最终结果后再投入生产。本页不为所有策略类型定义统一优先级；应以对应策略的后端和 Gateway 合同为准。

可用性与执行边界

Dashboard 使用以下状态：

状态含义
Always On当前工作区无法停用的基础控制
Active / Off已持久化并处于启用或停用状态的控制
套餐限制控制项可见，但需要其他套餐
Coming Soon / unavailable当前产品或运行模式暂不可用

应分别检查配置状态、Gateway 执行结果和可观测记录。表单保存成功只能确认控制平面配置；请求结果及其日志才能确认运行时行为。

相关页面