truefoundry-gateway

路由说明：对于含义不明确的用户意图，请使用 references/intent-clarification.md 中的通用澄清模板。

Gateway

配置和使用 TrueFoundry 的 AI Gateway：统一的 OpenAI 兼容大模型访问、提供商账户集成、内容安全护栏，以及请求监控和可观测性。

适用场景

• 通过 TrueFoundry 统一的 OpenAI 兼容网关访问大模型
• 配置身份验证令牌（PAT/VAT）、速率限制、预算控制，或跨提供商负载均衡
• 列出、创建或管理大模型提供商账户（OpenAI、AWS Bedrock、Google Vertex、Azure、Groq、Together AI、自定义 OpenAI 兼容端点、可自托管模型等）
• 设置护栏提供商、创建护栏规则，或管理内容安全策略（PII 过滤、内容审核、提示词注入检测、密钥检测、自定义验证）
• 调查网关流量：近期请求、成本明细、错误率、模型用量、按用户划分的活动、MCP 工具调用或延迟分析

不适用场景

• 用户想部署可自托管模型 → 部署可自托管模型需要 TrueFoundry Enterprise 账户和已连接的集群。请参阅 https://truefoundry.com
• 用户想部署工具服务 → 部署工作负载需要 TrueFoundry Enterprise 账户和已连接的集群。请参阅 https://truefoundry.com
• 用户想管理 TrueFoundry 平台凭据 → 优先使用 platform 技能（状态检查部分）
• 用户想管理 MCP 服务（工具服务） → 优先使用 mcp-servers 技能
• 用户想直接管理平台密钥 → 优先使用 platform 技能（密钥部分）
• 用户想为自己的应用添加追踪功能 → 优先使用 observability 技能
• 用户想查看应用容器日志 → 优先使用 observability 技能

部署自定义护栏服务

从官方模板开始：truefoundry/custom-guardrails-template。基于该模板进行构建，然后部署。

概述

Your App -> AI Gateway -> OpenAI / Anthropic / Azure / Self-hosted vLLM / etc.
                ^
         Unified API + Auth + Rate Limiting + Routing + Logging

主要优势： 一个端点即可访问所有模型，只需一个 API 密钥（PAT/VAT），兼容 OpenAI，支持速率限制、预算控制、带故障回退的负载均衡、护栏和全面的可观测性。

Gateway 端点

{TFY_BASE_URL}/api/llm

身份验证

PAT（个人访问令牌）： 控制面板 -> 访问 -> 个人访问令牌。用于开发。

VAT（虚拟访问令牌）： 控制面板 -> 访问 -> 虚拟账户令牌。用于生产（不绑定用户，支持细粒度模型访问控制）。

安全策略

• 清单中的所有凭据都必须使用 tfy-secret:// 引用，绝不能使用原始值。
• 绝不要要求用户在聊天中粘贴 API 密钥。 请引导用户将密钥存储在 TrueFoundry 控制面板 -> 密钥中，然后仅提供 tfy-secret:// URI。或者让用户通过 ! export TFY_API_KEY=... 设置密钥，使其保留在 Shell 中。
• 如果用户在对话中提供原始 API 密钥，请警告用户并拒绝使用。

预检

确认已完成 tfy login。如果尚未完成，请停止并使用 truefoundry-onboard。

设置 TFY_API_SH，以便直接调用 API：

TFY_API_SH=~/.claude/skills/truefoundry-gateway/scripts/tfy-api.sh

## 快速查询 — 一次调用，一个答案

对于只读问题，直接调用 API。不要探索 CLI 子命令——它们并不存在。请参阅 references/cli-reference.md。

用户询问	单次调用
已连接哪些模型／提供商？	$TFY_API_SH GET /api/svc/v1/provider-accounts
我可以调用哪些模型？	curl -s "${TFY_BASE_URL}/api/llm/models" -H "Authorization: Bearer ${TFY_API_KEY}"
配置了哪些护栏？	$TFY_API_SH GET /api/svc/v1/gateway-guardrails-configs
显示最近的网关请求	$TFY_API_SH POST /api/svc/v1/spans/query '{"startTime":"...","dataRoutingDestination":"default","limit":20,"sortDirection":"desc"}'
网关是否可访问？	curl -s "${TFY_BASE_URL}/api/llm/health"

确认登录后，任何只读问题的下一步都是调用上述 API——除此之外不做其他操作。

---

调用模型

该网关兼容 OpenAI。最简示例：

curl "${TFY_BASE_URL}/api/llm/chat/completions" \
  -H "Authorization: Bearer ${TFY_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"model": "openai/gpt-4o", "messages": [{"role": "user", "content": "Hello!"}], "max_tokens": 200}'

也可以为任意 OpenAI SDK 设置环境变量：

export OPENAI_BASE_URL="${TFY_BASE_URL}/api/llm"
export OPENAI_API_KEY="<your-PAT-or-VAT>"

完整的 SDK 示例（Python、Node.js、流式传输）、支持的 API 表格、框架集成（LangChain、LlamaIndex、Cursor），以及路由／速率限制／预算配置，请参阅 references/calling-models.md。

---

提供商集成

列出提供商账户

$TFY_API_SH GET /api/svc/v1/provider-accounts

以格式化表格呈现，包含名称、提供商、类型和模型数量（取自 integrations 数组长度）。

创建提供商账户

1. 首先确保凭据已存储为 TrueFoundry 密钥（platform 技能的 Secrets 部分）
2. 使用 references/provider-templates.md 中合适的提供商模板
3. 应用配置：$TFY_API_SH POST /api/svc/v1/provider-accounts "$payload"

支持的提供商：OpenAI、AWS Bedrock、Google Vertex、Azure OpenAI、Groq、Together AI、Custom（任何兼容 OpenAI 的服务）、Self-Hosted、TrueFoundry。

应用配置（任何网关资源）

tfy apply -f manifest.yaml --dry-run --show-diff
tfy apply -f manifest.yaml

不要将网关配置的应用操作委派给部署技能。网关配置应通过 tfy apply 内联应用。

---

护栏

护栏用于添加内容安全控制。设置需要两个步骤：

1. 创建护栏配置组 — 注册提供商集成
2. 创建网关护栏配置 — 创建引用这些提供商的规则

快速列表：$TFY_API_SH GET /api/svc/v1/gateway-guardrails-configs

完整的设置说明、规则结构、API 调用和常见模式，请参阅 references/guardrails-setup.md。

支持的提供商参考：references/guardrail-providers.md。

---

AI 监控

通过 spans API 查询网关请求跟踪，并通过 metrics API 汇总用量。跟踪查询需要 tracingProjectFqn 或 dataRoutingDestination；如果用户不知道目标位置，建议先使用 "default"。

最近的请求

$TFY_API_SH POST /api/svc/v1/spans/query '{
  "dataRoutingDestination": "default",
  "startTime": "2026-05-15T00:00:00.000Z",
  "limit": 20,
  "sortDirection": "desc"
}'

将结果整理为格式化表格（时间、模型、状态、令牌数、成本、延迟、用户）。

所有监控用例（成本分析、错误、模型用量、用户筛选、MCP 工具调用、元数据筛选）、筛选类型、响应结构和分页，请参阅 references/monitoring.md。

汇总指标

对于以下汇总类问题，请使用此路径：

• “显示过去 3 个月产生的成本。”
• “按模型、用户、团队或虚拟账户细分成本。”
• “显示各模型的令牌总数和延迟。”
• “哪个虚拟账户产生的成本最高？”

$TFY_API_SH POST /api/svc/v1/llm-gateway/metrics/query '{
  "startTs": "...", "endTs": "...",
  "datasource": "modelMetrics",
  "type": "distribution",
  "aggregations": [{"type": "sum", "column": "costInUSD"}],
  "groupBy": ["modelName"]
}'

回答时间范围相关的问题时，请计算准确的 startTs 和 endTs，说明所用范围，并以简洁的表格呈现总计。如果用户要求按月细分，除非 API 提供时间分桶字段，否则每月运行一次查询。

---

生成清单

对于任何网关实体或策略：

1. 获取现有配置 — 调用「快速查找」中的 API
2. 查阅架构参考 — 参见下表
3. 生成 YAML — 凭据使用 tfy-secret://
4. 验证 — tfy apply -f manifest.yaml --dry-run --show-diff
5. 应用 — tfy apply -f manifest.yaml

实体	参考
Provider 账户	references/provider-templates.md
虚拟模型 / 路由	references/calling-models.md（虚拟模型部分）
速率限制	references/schemas/rate-limiting.md
预算控制	references/schemas/budget-limiting.md
护栏	references/guardrails-setup.md
可观测性表	references/observability.md

<success_criteria>

成功标准

AI 网关

• 用户可以通过兼容 OpenAI 的 SDK 或 cURL 使用网关调用大模型
• 已配置有效的 PAT 或 VAT
• 已确认目标模型名称可用
• 已用用户所用语言 / 框架提供可运行的代码片段

Provider 集成

• 以格式化表格列出 Provider 账户
• 新建 Provider 账户的所有凭据均使用 tfy-secret://
• 创建前确认 Provider 类型和模型详情

护栏

• 列出护栏配置组
• 规则正确匹配目标模型、用户和工具
• 执行创建 / 更新操作前先确认

AI 监控

• 显示近期追踪记录及其时间戳、模型、状态和费用
• 以格式化表格而非原始 JSON 展示结果
• 查询前询问 dataRoutingDestination 或 tracingProjectFqn

</success_criteria>

参考资料

核心

• cli-reference.md — CLI 命令、标志及不存在的功能
• api-endpoints.md — 完整 REST API 和 curl 示例

网关操作

• calling-models.md — SDK 示例、路由、速率限制、预算和框架
• provider-templates.md — 所有 Provider 清单模板（OpenAI、Bedrock、Vertex、Azure 等）
• guardrails-setup.md — 护栏配置组和规则设置
• monitoring.md — Spans 查询 API、指标和用例
• guardrail-providers.md — 全部 23 种护栏 Provider 类型

架构

• schemas/provider-account.md — Provider 账户架构
• schemas/virtual-model.md — 虚拟模型 / 负载均衡架构
• schemas/rate-limiting.md — 速率限制架构
• schemas/budget-limiting.md — 预算控制架构
• schemas/guardrail-config.md — 护栏配置架构

其他

• access-management.md — 身份、PAT/VAT、权限
• integrations.md — 原生 SDK 代理、IDE 集成
• observability.md — SQL 查询模式
• span-attributes.md — 60 多种 span 属性定义

组合使用

• 先存储凭据：platform skill（Secrets 部分）-> 然后使用 tfy-secret:// URI
• 需要 API 密钥：Dashboard -> Access -> Personal Access Tokens 或 Virtual Accounts
• MCP 服务：mcp-servers skill
• 部署模型：需要 TrueFoundry Enterprise 和已连接的集群
• 为应用添加监测：observability skill（Tracing 部分）

错误处理

401 Unauthorized

API 密钥（PAT/VAT）无效或已过期。检查 Authorization: Bearer <token> 标头。

403 Forbidden

令牌无权访问此模型。PAT 会继承用户权限；VAT 只能访问明确选定的模型。

404 Model Not Found

网关中没有此模型名称。请通过 dashboard -> AI Gateway -> Models 或 GET /api/llm/models 查看确切名称。

429 Rate Limited

请等待后重试（检查 Retry-After 响应头）。申请提高限制，或使用负载均衡。

502/503 Provider Error

上游提供商出现问题。如果已配置路由，网关会自动重试或回退。请查看提供商状态页面。

Permission Denied (Provider Accounts)

用户需要 provider-account-manager 角色。请检查提供商账户的协作者。

Invalid Secret Reference

无法解析 tfy-secret:// 路径。请验证格式：tfy-secret://TENANT:SECRET_GROUP:SECRET_KEY。使用 platform 技能检查密钥组是否存在。

Type Filter Not Working

GET /api/svc/v1/provider-accounts 上的 type 查询参数不会进行筛选。请获取所有结果，然后在客户端进行筛选。

Provider Account Name Already Exists

请使用其他名称，或更新现有账户。

Model Not Appearing in Gateway After Creation

请验证：提供商账户已成功创建；集成配置了正确的 model_types；协作者中包含 team:everyone 或相关用户。

No Monitoring Data

请检查：时间范围是否正确，dataRoutingDestination 是否存在，筛选条件是否过于严格，以及网关是否已收到请求。

400 Bad Request (Monitoring)

缺少必需参数。请确保提供 tracingProjectFqn 或 dataRoutingDestination，并提供有效的 ISO 8601 格式 startTime。