按客户策略

Beta版： LLM网关处于 beta测试阶段。

支出策略或速率限制策略可以包含基于自定义请求头的条件，这样来自同一主体的流量会根据头部分值被拆分为独立的限额。使用此功能，您可以为自己的终端客户、租户或团队设置上限，而无需为每个团队发放单独的 LangSmith API密钥。例如，一个限定于某个工作区的策略，如果条件是 X-Gateway-Customer-Id: acme，则它只限制来自该工作区且携带该头部值的请求。来自同一工作区但携带 X-Gateway-Customer-Id: globex 的请求，则计入另一个策略的限额。

可匹配的头部

网关匹配以 X-Gateway- 为前缀的请求头，以及 X-Gateway-Metadata JSON头内部的键。其他请求头均不可匹配。头部名称在匹配前会进行标准化处理：去掉 X-Gateway- 前缀，剩余部分转为小写，并将 a-z、0-9 和 _ 以外的每个字符替换为 _。头部 X-Gateway-Customer-Id、x-gateway-customer_id 和 X-Gateway-CUSTOMER.ID 均会解析为匹配器键 customer_id。头部值作为精确、区分大小写的字符串进行比较，不支持通配符或模式匹配。网关会自行记录调用者身份，并忽略客户端覆盖它的尝试。解析为 organization_id、workspace_id、workspace_handle、user_id、user_email、api_key_id、api_key_short、auth_mode、user_agent、applied_policy_ids 或 applied_policy_names 的头部，以及任何标准化后以 gateway 开头的头部，均会被丢弃。

头部条件规则

每个策略一个条件：一个策略接受一个头部键和一个值。
与一个主体范围配对：将头部条件与一个组织、工作区、用户或API密钥范围结合。主体一侧接受多个值并匹配其中任何一个。头部一侧只接受一个值。
仅适用于支出上限和速率限制：默认策略不能携带头部条件，因此网关不会自行创建按头部划分的策略。要限制多个头部值，需为每个值创建一个策略。
缺少头部则不匹配：不携带该头部的请求不会匹配该策略。将按头部策略与主体上更广泛的策略配对，以便未标记的流量仍受限制。
每个匹配的策略都会被执行：同时匹配一个普通主体策略和一个带头部条件的策略的请求，将计入两者的限额，且任意一个都可能阻止它。
最多10个条件：一个策略总共携带的主体条件不超过10个。

添加头部条件

创建和管理策略需要 organization:manage 权限。有关完整的权限分解，请参阅跟踪、引擎和访问控制。

前往 设置 → 网关 → LLM网关。
点击 创建策略。
选择策略类型和主体范围，然后设置限制。
在 自定义头部条件（可选） 下，输入不带 X-Gateway- 前缀的 头部名称（例如，Customer-Id）和要匹配的 头部值（例如，acme）。
保存。

策略创建后，您无法在用户界面中编辑头部条件。要更改它，请删除该策略并创建一个新的，或通过API更新 subject_matchers。

为每个终端客户设置支出上限

经销商或多租户应用通常从其自己的后端调用网关，代表多个终端客户使用一个工作区范围的API密钥。头部条件让这些终端客户在该单一密钥下拥有各自独立的支出上限。

网关信任传入请求上的 X-Gateway-* 头部。在您的后端对终端用户进行身份验证后设置该头部，并且不要将网关API密钥分发给终端用户。同时控制密钥和头部的调用者可以选择将支出计入哪个上限。

步骤1. 在每次调用时发送客户头部

在您的后端代表终端客户发出的每个请求中附上该头部：

curl https://gateway.smith.langchain.com/openai/v1/chat/completions \
    -H "Authorization: Bearer $LANGSMITH_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Gateway-Customer-Id: acme" \
    -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"ping"}]}'

import os

from openai import OpenAI

client = OpenAI(
    base_url=os.environ["OPENAI_BASE_URL"],
    api_key=os.environ["LANGSMITH_API_KEY"],
)
customer_id = "acme"
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "ping"}],
    extra_headers={"X-Gateway-Customer-Id": customer_id},
)
print(response.choices[0].message.content)

如果您的LangSmith账户位于区域实例，请使用相应的区域网关。

步骤2. 为一个客户创建上限

通过 LangSmith REST API 为每个终端客户创建一个支出策略：

curl -X POST "https://api.smith.langchain.com/v1/platform/gateway-policies" \
    -H "X-Api-Key: $LANGSMITH_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
          "name": "customer-acme-monthly-cap",
          "policy_type": "spend_cap",
          "action": "block",
          "subject_matchers": [
            {"key": "workspace_id", "value": "0b1c2d3e-4f56-7890-abcd-ef1234567890"},
            {"key": "customer_id", "value": "acme"}
          ],
          "config": {"window": "monthly", "limit_usd": 250}
        }'

import os

import httpx

response = httpx.post(
    "https://api.smith.langchain.com/v1/platform/gateway-policies",
    headers={"X-Api-Key": os.environ["LANGSMITH_API_KEY"]},
    json={
        "name": "customer-acme-monthly-cap",
        "policy_type": "spend_cap",
        "action": "block",
        "subject_matchers": [
            {"key": "workspace_id", "value": "0b1c2d3e-4f56-7890-abcd-ef1234567890"},
            {"key": "customer_id", "value": "acme"},
        ],
        "config": {"window": "monthly", "limit_usd": 250},
    },
    timeout=30.0,
)
response.raise_for_status()

匹配器键是标准化后的名称 customer_id，而不是头部名称 X-Gateway-Customer-Id。该策略属于拥有该API密钥的组织。发布一个 subject_matchers 已经存在的策略会更新该策略，而不是添加重复项，因此此调用可以安全地重复执行。

步骤3. 将策略与您的客户列表同步

由于每个终端客户都需要自己的策略，请保持策略集与您的客户列表同步。以下脚本为每个当前客户创建或更新一个上限，然后删除已不复存在的客户的上限：

import os

import httpx

API_URL = "https://api.smith.langchain.com/v1/platform/gateway-policies"
WORKSPACE_ID = os.environ["LANGSMITH_WORKSPACE_ID"]

# 您的真实数据源：终端客户标识符映射到以美元为单位的月度支出上限。
CUSTOMER_CAPS = {"acme": 250.0, "globex": 1000.0, "initech": 50.0}


def matchers_for(customer: str) -> list[dict[str, str]]:
    return [
        {"key": "workspace_id", "value": WORKSPACE_ID},
        {"key": "customer_id", "value": customer},
    ]


def existing_caps(client: httpx.Client) -> dict[str, dict]:
    """返回当前的按客户支出上限，以客户标识符为键。"""
    response = client.get(API_URL, params={"policy_type": "spend_cap"})
    response.raise_for_status()
    return {
        matcher["value"]: policy
        for policy in response.json()
        for matcher in policy["subject_matchers"]
        if matcher["key"] == "customer_id"
    }


def sync() -> None:
    headers = {"X-Api-Key": os.environ["LANGSMITH_API_KEY"]}
    with httpx.Client(headers=headers, timeout=30.0) as client:
        existing = existing_caps(client)

        # 发布一组已存在的匹配器会更新该策略，因此此操作既为新客户创建上限，
        # 也修正已更改的上限。
        for customer, limit_usd in CUSTOMER_CAPS.items():
            client.post(
                API_URL,
                json={
                    "name": f"customer-{customer}-monthly-cap",
                    "policy_type": "spend_cap",
                    "action": "block",
                    "subject_matchers": matchers_for(customer),
                    "config": {"window": "monthly", "limit_usd": limit_usd},
                },
            ).raise_for_status()

        # 删除任何不在 CUSTOMER_CAPS 中的按客户上限，包括在此脚本之外创建的上限。
        for customer, policy in existing.items():
            if customer not in CUSTOMER_CAPS:
                client.delete(f"{API_URL}/{policy['id']}").raise_for_status()


if __name__ == "__main__":
    sync()

每当客户注册、流失或更换到不同的套餐时运行此脚本。

步骤4. 读取每个客户的支出

API返回的每个支出策略都报告 current_spend_usd，即该策略活动窗口内累积的支出。可用它向每个终端客户展示其使用情况，或在他们接近上限时发出警告。当支出查询失败时，该字段会被省略，因此应将缺失值视为未知，而不是零。列表端点仅在某个主体匹配器键与值配对时才会缩小范围，因此请列出支出上限并在您自己的代码中选择按客户的上限：

import os

import httpx

response = httpx.get(
    "https://api.smith.langchain.com/v1/platform/gateway-policies",
    headers={"X-Api-Key": os.environ["LANGSMITH_API_KEY"]},
    params={"policy_type": "spend_cap"},
    timeout=30.0,
)
response.raise_for_status()

for policy in response.json():
    customer = next(
        (m["value"] for m in policy["subject_matchers"] if m["key"] == "customer_id"),
        None,
    )
    if customer is None:
        continue  # 工作区本身的上限，而不是某个终端客户的上限。
    # 当支出查询失败时，current_spend_usd 不存在。
    print(customer, policy.get("current_spend_usd"), policy["config"]["limit_usd"])

限制每个终端客户的吞吐量

速率限制使用相同的主体匹配器。替换 policy_type 和 config 以为终端客户提供其自己的请求和令牌配额：

curl -X POST "https://api.smith.langchain.com/v1/platform/gateway-policies" \
    -H "X-Api-Key: $LANGSMITH_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
          "name": "customer-acme-rate-limit",
          "policy_type": "rate_limit",
          "action": "block",
          "subject_matchers": [
            {"key": "workspace_id", "value": "0b1c2d3e-4f56-7890-abcd-ef1234567890"},
            {"key": "customer_id", "value": "acme"}
          ],
          "config": {
            "version": 1,
            "limits": [
              {"metric": "requests", "window": "minute", "value": 100},
              {"metric": "tokens", "window": "hour", "value": 1000000}
            ]
          }
        }'

步骤3 中的同步脚本同样适用于速率限制，只需进行相同的两处替换。支出上限和速率限制是独立的策略类型，因此一个终端客户可以为同一个头部值同时持有两者。

后续步骤

支出策略：为组织、工作区、用户和API密钥设置成本上限。
速率限制策略：在滚动窗口内限制请求和令牌。
跟踪和访问控制：了解网关跟踪数据去向以及谁可以配置策略。

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Core capabilities

Administration and governance

Advanced

可匹配的头部

头部条件规则

添加头部条件

为每个终端客户设置支出上限

步骤1. 在每次调用时发送客户头部

步骤2. 为一个客户创建上限

步骤3. 将策略与您的客户列表同步

步骤4. 读取每个客户的支出

限制每个终端客户的吞吐量

后续步骤

​可匹配的头部

​头部条件规则

​添加头部条件

​为每个终端客户设置支出上限

​步骤1. 在每次调用时发送客户头部

​步骤2. 为一个客户创建上限

​步骤3. 将策略与您的客户列表同步

​步骤4. 读取每个客户的支出

​限制每个终端客户的吞吐量

​后续步骤

可匹配的头部

头部条件规则

添加头部条件

为每个终端客户设置支出上限

步骤1. 在每次调用时发送客户头部

步骤2. 为一个客户创建上限

步骤3. 将策略与您的客户列表同步

步骤4. 读取每个客户的支出

限制每个终端客户的吞吐量

后续步骤