尧图网站建设 
Portkey AI Gateway 实战指南一套 API 统一路由 1600 LLM、自动重试、负载均衡与 AI 守卫【免费下载链接】gatewayA blazing fast AI Gateway with integrated guardrails. Route to 1,600 LLMs, 50 AI Guardrails with 1 fast friendly API.项目地址: https://gitcode.com/GitHub_Trending/ga/gateway本篇技术指南围绕开源项目 Portkey AI Gateway 的核心能力展开如何用一条命令在 2 分钟内启动网关通过 OpenAI 兼容的 SDK 统一接入数百家大模型如何使用 config 配置实现自动重试、fallback、负载均衡、条件路由与输入/输出守卫guardrails以及网关在安全、成本、可观测性与多模态、Realtime 等方向的架构设计。读完本文你将掌握基于该网关搭建高可用、可治理的 LLM 接入层的完整实战方案并了解其底层实现原理。项目定位一个轻量、可自托管的 AI 网关Portkey AI Gateway 是一个开源的 AI 网关AI GatewayREADME 将其定位为用一套快速且友好的 API将请求路由到 1600 语言、视觉、音频与图像模型轻量、开源、面向企业级生产环境集成时间可控制在 2 分钟以内。README 中给出的关键特征包括极快的转发延迟README 称 1ms与极小的体积README 称 122kb经过大规模生产验证README 称每日处理超过 100 亿 token企业级就绪增强的安全、规模扩展与自定义部署能力。以上数据均为 README 中的官方描述实际性能会随部署环境而异。值得注意的是当前仓库 package.json 中的版本为1.15.2README 顶部还预告了 Gateway 2.0Pre-Release——Portkey 的核心企业网关将随 2.0 版本合并入开源代码预发布分支可单独体验。从源码结构看网关核心位于 src/index.ts它基于 Hono 框架构建兼容 Node.js 与 Cloudflare Workersworkerd等运行时。src/index.ts中注册了/v1/chat/completions、/v1/completions、/v1/embeddings、/v1/images/generations、/v1/audio/speech、/v1/audio/transcriptions、/v1/audio/translations、/v1/messagesAnthropic 格式、/v1/files、/v1/batches、/v1/responses、/v1/fine_tuning/jobs、/v1/models等一整套 OpenAI/Anthropic 风格端点并用proxyHandler兜底处理其余/v1/*请求。这意味着你几乎可以把任意 LLM 请求原样交给网关由它负责协议转换与路由。2 分钟快速开始第一步本地启动网关README 给出的最快启动方式是一条npx命令需要本机已安装 Node.js 和 npmnpx portkey-ai/gateway启动后网关 API 地址为http://localhost:8787/v1网关控制台Gateway Console地址为http://localhost:8787/public/端口号与默认值的细节可以从 src/start-server.ts 中得到源码级确认默认端口为8787支持通过命令行参数--port覆盖支持--headless参数非 headless 模式下才会注册/public/与/public/logs的静态页面路由以及/log/stream的 SSE 日志流接口用于在浏览器中实时查看本地日志/v1/realtime路由通过 WebSocket 提供服务upgradeWebSocket(realTimeHandlerNode)用于接入 OpenAI 风格的 Realtime API。也可以从仓库源码构建后运行# 克隆仓库仓库地址用于说明 git clone 场景 git clone https://gitcode.com/GitHub_Trending/ga/gateway cd gateway npm i npm run build node build/start-server.js对应脚本定义在 package.json 的dev:nodetsx src/start-server.ts与start:nodenode build/start-server.js中。第二步发出第一个请求网关提供 OpenAI 兼容接口因此你既可以用 Portkey 官方 Python SDK也可以直接使用 OpenAI SDK、REST 调用。README 的 Python 示例# pip install -qU portkey-ai from portkey_ai import Portkey # OpenAI 兼容客户端 client Portkey( provideropenai, # 或 anthropic, bedrock, groq 等 Authorizationsk-*** # 提供方 API Key ) # 通过 AI Gateway 发起请求 client.chat.completions.create( messages[{role: user, content: Whats the weather like?}], modelgpt-4o-mini )provider参数决定请求被路由到哪家模型服务商。仓库 src/globals.ts 中的VALID_PROVIDERS数组列出了网关当前支持的全部 provider 标识包括openai、azure-openai、anthropic、bedrock、groq、google、vertex-ai、mistral-ai、together-ai、stability-ai、ollama、deepseek、zhipu、x-ai、oracle、sagemaker、cortex等上百个常量对应 src/providers 目录下同名的提供方实现每个目录通常包含api.ts、chatComplete.ts、complete.ts、embed.ts等文件。除 Python 外README 提到网关同样支持 JS、纯 REST、OpenAI SDK、LangChain、LlamaIndex、Autogen、CrewAI 等多种接入方式仓库 cookbook 目录中提供了大量可运行的集成示例例如 cookbook/integrations/vercel-ai.mdVercel AI SDK 接入、cookbook/integrations/langchain.ipynbLangChain 接入等。第三步在 Console 查看日志README 指出在 Gateway Consolehttp://localhost:8787/public/可以看到全部本地日志。从 src/start-server.ts 的实现看/log/stream通过 SSE 把日志实时推送给浏览器包含连接事件connected、心跳heartbeat等协议细节Cache-Control: no-cache与X-Accel-Buffering: no头确保日志不被缓冲、实时可见。路由与守卫用 Config 给请求附加可靠性策略README 明确指出网关中的Configs让你可以创建路由规则、增加可靠性配置并设置守卫guardrails。下面这段示例是 README 的核心演示同时用到了重试与输出守卫config { retry: {attempts: 5}, output_guardrails: [{ default.contains: {operator: none, words: [Apple]}, deny: True }] } # 将 config 挂到客户端 client client.with_options(configconfig) client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: Reply randomly with Apple or Bat}] ) # 由于守卫会拒绝所有包含 Apple 的回答最终总是返回 Bat # retry 配置则会在失败时最多重试 5 次。这段示例同时展示了网关两个核心机制retry自动重试retry.attempts指定最大重试次数README 示例为 5与 src/globals.ts 中的MAX_RETRIES 5一致。重试的底层实现在 src/handlers/retryHandler.ts 的retryRequest函数中值得关注的设计点默认重试状态码RETRY_STATUS_CODES [429, 500, 502, 503, 504]定义于 src/globals.ts即限流与常见的 5xx 服务端错误会触发重试请求级超时返回 408REQUEST_TIMEOUT_STATUS_CODE指数退避基于async-retry库实现randomize: false关闭随机抖动靠退避间隔错开重试请求避免网络过载尊重提供方重试头当响应为 429 且配置了followProviderRetry时网关会读取retry-after-ms、x-ms-retry-after-ms、retry-after头POSSIBLE_RETRY_STATUS_HEADERS按提供方建议的等待时间重试总重试时间上限MAX_RETRY_LIMIT_MS 60 * 100060 秒如果提供方要求的等待时间超过剩余预算网关会跳过本次重试直接返回错误连接级错误兜底遇到 DNS/连接失败ConnectTimeoutError返回 503其余未带 status 的错误返回 500保证任何情况下都能拿到结构化响应。配置层面的类型定义在 src/types/requestBody.ts 中字段类型说明attemptsnumber最大重试次数onStatusCodesnumber[]指定哪些 HTTP 状态码触发重试覆盖默认的 429/500/502/503/504useRetryAfterHeaderboolean是否使用提供方返回的 retry-after 等待时间output_guardrailsAI 守卫示例中的default.contains是网关内置的默认守卫插件之一。它对应的实现是 plugins/default/contains.ts插件从响应文本中统计命中的词foundWords与缺失的词missingWords按operator判定any命中任意一个词即通过all全部词都出现才通过none一个词都不出现才通过示例使用此模式因此任何包含 Apple 的输出都被拒绝。结合deny: True一旦守卫判定失败请求即被拦截。守卫的底层执行机制是把 config 中的input_guardrails/output_guardrails转换为 before/after 请求钩子hooks——src/handlers/handlerUtils.ts 中的convertHooksShorthand负责这一转换它会解析deny、on_fail、on_success、async、id等公共字段把剩余键包装成default.${checkId}形式的检查项最终挂到beforeRequestHooks/afterRequestHooks上执行。仓库的 plugins/default 目录内置了大量默认守卫例如contains、wordCount、sentenceCount、characterCount、regexMatch、regexReplace、jsonSchema、jwt、modelWhitelist、modelRules、validUrls、webhook、requiredMetadataKeys等并配套有 plugins/default/default.test.ts 单元测试。README 称共有 40 个预置守卫可选除内置插件外仓库还集成了多家第三方守卫供应商插件见 plugins 目录acuvity、aporia、azure内容安全/PII/受保护素材、bedrock、crowdstrike-aidr、exa、f5-guardrails、javelin、lasso、mistral、pangea、panw-prisma-airs、patronus、pillar、portkey、promptfoo、promptsecurity、qualifire、sydelabs、walledai等。哪些插件默认启用由 conf.example.json 中的plugins_enabled数组决定默认启用了default、portkey、aporia、sydelabs、pillar、patronus、pangea、promptsecurity、panw-prisma-airs、walledai。通过请求头发送 config除了 SDK 方式挂载 config网关还支持通过请求头传递配置x-portkey-*系列头前缀由 src/globals.ts 中的POWERED_BY portkey决定。constructConfigFromRequestHeaders位于 src/handlers/handlerUtils.ts会解析这些头包括x-portkey-api-key、x-portkey-provider、x-portkey-config、x-portkey-retry-count、x-portkey-cache、x-portkey-metadata、x-portkey-forward-headers、x-portkey-custom-host、x-portkey-request-timeout、x-portkey-strict-open-ai-compliance、x-portkey-virtual-key等以及各类提供方专属头Azure、AWS Bedrock、Vertex、SageMaker、Stability 等。这在不想改代码、只想临时指定路由策略的场景下非常实用。核心特性源码级解析README 把核心特性归纳为四类可靠路由、安全与准确、成本管理、协作与工作流。下面逐项展开。可靠路由Reliable RoutingREADME 列出的可靠路由能力包括Fallbacks故障回退请求失败时回退到另一个提供方或模型且可以指定触发回退的错误码。路由策略定义在 src/types/requestBody.ts 的StrategyModesloadbalance、fallback、single、conditional。回退逻辑在 src/handlers/handlerUtils.ts 的tryTargetsRecursively中fallback 模式下按顺序遍历targets只有当响应状态命中strategy.onStatusCodes或响应非 ok、或标记为网关异常x-portkey-gateway-exception: true时才继续尝试下一个目标Automatic Retries自动重试最多重试 5 次指数退避见上文 retry 解析Load Balancing负载均衡把请求按权重分发到多个 API Key 或多个提供方。selectProviderByWeight与tryTargetsRecursively的LOADBALANCE分支实现加权随机选择权重缺省为 1确保高可用与最优性能Request Timeouts请求超时可设置细粒度的请求超时超过时长的请求会被自动终止408 响应见retryHandler.ts的fetchWithTimeoutMulti-modal LLM Gateway多模态以统一的 OpenAI 签名调用视觉、音频TTS 与 STT、图像生成模型。这在 src/index.ts 的路由注册中可看到/v1/audio/speech、/v1/audio/transcriptions、/v1/audio/translations、/v1/images/generations、/v1/images/edits均有独立 handlerRealtime APIs实时接口通过内置的 WebSocket 服务器/v1/realtime接入 OpenAI 发布的 Realtime APINode 与 workerd 运行时各有实现src/handlers/realtimeHandlerNode.ts 与 src/handlers/realtimeHandler.ts。此外还有条件路由Conditional Routingstrategy.mode conditional时网关根据 metadata、请求参数或 URL 路径选择目标。实现位于 src/services/conditionalRouter.ts支持丰富的查询操作符$eq、$ne、$gt、$gte、$lt、$lte、$in、$nin、$regex以及逻辑组合$and/$or并可配置default目标作为兜底。条件路由配合 circuit breaker熔断等能力可以从源码中看到tryTargetsRecursively会过滤掉isOpen的异常目标。安全与准确Security AccuracyGuardrails守卫对 LLM 输入与输出做合规校验内置 40 预置守卫可自带守卫bring your own guardrails或选用多家合作供应商见上文插件列表Secure Key Management密钥管理既可用自己的 API Key也可按需动态生成虚拟 Keyx-portkey-virtual-key实现密钥不落盘、按需分发RBAC基于角色的访问控制对用户、工作空间与 API Key 做细粒度访问控制合规与数据隐私README 声明网关符合 SOC2、HIPAA、GDPR 与 CCPA 标准属 README 表述具体合规认证情况请以官方渠道为准。成本管理Cost ManagementSmart Caching智能缓存缓存 LLM 响应以降低成本、降低延迟支持简单缓存与语义缓存。本地内存缓存由 src/index.ts 中的memoryCache中间件与 src/handlers/services/cacheService.ts 实现配置conf.cache true即启用。此外 src/index.ts 还支持REDIS_CONNECTION_STRING环境变量Node 运行时下可切换到 Redis 缓存后端Usage Analytics用量分析监控请求量、延迟、成本与错误率网关在 src/handlers/services/logsService.ts 中记录每次请求的完整日志含缓存状态、重试次数、hook 链路 ID 等Provider Optimization根据用量模式与定价模型自动切换最经济的提供方README 标注为托管版与企业版能力。协作与工作流Collaboration WorkflowsAgents 支持与 Autogen、CrewAI、LangChain、LlamaIndex、Phidata、Control Flow 等流行 Agent 框架无缝集成也支持自定义 Agent。仓库 cookbook/integrations 下有大量对应 notebookPrompt Template Management通过统一的 prompt 游乐场创建、管理与版本化提示模板README 标注为托管版与企业版能力网关侧提供/v1/prompts/*端点见 src/index.ts。MCP GatewayMCP 服务器的统一控制面README 还介绍了独立的 MCP Gateway 能力为组织内的 MCPModel Context Protocol服务器提供集中控制平面认证Authentication网关层单一认证用户只需认证一次MCP 服务器收到的是已验证的请求访问控制Access Control控制哪些团队/用户可访问哪些服务器与工具可即时撤销访问可观测性Observability每次工具调用都会记录完整上下文谁调用了什么、参数、响应、延迟身份转发Identity Forwarding自动把用户身份邮箱、团队、角色转发给 MCP 服务器。它兼容 Claude Desktop、Cursor、VS Code 以及任何 MCP 兼容客户端。支持的提供方与 Agent 框架README 给出了一个提供方支持矩阵部分节选均支持流式提供方SupportStreamOpenAI✅✅Azure OpenAI✅✅Anyscale✅✅Google Gemini✅✅Anthropic✅✅Cohere✅✅Together AI✅✅Perplexity✅✅Mistral✅✅Nomic✅✅AI21✅✅Stability AI✅✅DeepInfra✅✅Ollama✅✅Novita AI✅✅完整清单以 src/globals.ts 的VALID_PROVIDERS与 src/providers 目录为准——从目录看当前仓库实际实现了 100 个提供方模块含azure-ai-inference、google-vertex-ai、sagemaker、x-ai、z-ai、oracle等README 称支持 45 提供方集成与 8 Agent 框架。值得注意的是 README 同时声称覆盖 1600 模型、200 模型完整列表可查这些数字属于项目方宣传口径实际以源码与官方文档为准。Agent 框架方面README 的表格显示 Autogen、CrewAI、LangChain、Phidata、LlamaIndex、Control Flow 及自建 Agent 均支持调用 200 LLM、高级路由、缓存、日志与追踪、可观测性、提示管理后几项标注为托管版能力。部署方式README 提供了丰富的部署选项详细步骤见 docs/installation-deployments.md此处摘要如下方式命令 / 说明npm / npxnpx portkey-ai/gateway需要 Node.jsBunbunx portkey-ai/gatewayNode.js Server克隆仓库 →npm i npm run build→node build/start-server.jsDockerdocker run --rm -p 8787:8787 portkeyai/gateway:latestDocker Composedocker compose up -d使用仓库内 docker-compose.yamlCloudflare Workersnpm run deploy基于 wrangler.toml 与 src/index.tsReplit一键部署详见 docs/deploy-on-replit.mdKubernetes / AWS EC2 / F5 App Stack / Supabase Functions / Fastly / Zeabur详见部署文档仓库根目录还提供了 deployment.yamlKubernetes 部署清单、Dockerfile 与 docker-compose.yaml。由于网关核心基于 Hono天然支持在 Node、workerdCloudflare Workers、lagon 等运行时上运行src/index.ts 中会按运行时跳过不必要的压缩中间件避免双重压缩并差异化管理 WebSocket 与静态页面。企业版与自托管扩展README 介绍的企业版私有部署在开源网关之上叠加了Secure Key Management基于角色的访问控制与用量追踪Simple Semantic Caching更快地服务重复查询并节省成本Access Control Inbound Rules控制哪些 IP 与地域可以连接你的部署PII Redaction自动从请求中移除敏感数据防止意外泄露SOC2、ISO、HIPAA、GDPR 合规README 表述专业支持与特性优先排期。企业版支持 AWS、Azure、GCP、OpenShift、Kubernetes 等平台的私有部署。总结与延伸阅读Portkey AI Gateway 的价值在于把接入多家 LLM 可靠路由 安全治理沉淀为一条可自托管的网关层对外提供 OpenAI 兼容 API对内通过configSDK 对象或x-portkey-*请求头声明式地编排重试、回退、负载均衡、条件路由与守卫并由插件体系plugins支撑可扩展的输入/输出检查。对于希望进一步上手的读者可以继续阅读docs/installation-deployments.md完整部署矩阵cookbook获取 Nvidia NIM、CrewAI 监控、LMSYS 模型对比、Vercel AI SDK 等实战 notebookconf.example.json网关配置示例插件启用、提供方凭证、限流与模型定价plugins/default内置守卫插件源码与 plugins/default/default.test.ts 测试用例src/handlers/retryHandler.ts 与 src/services/conditionalRouter.ts重试与条件路由的核心实现。整体来看该网关是一套API 兼容层 策略引擎 插件化守卫的三层架构适合作为企业统一 LLM 接入层的自托管底座。【免费下载链接】gatewayA blazing fast AI Gateway with integrated guardrails. Route to 1,600 LLMs, 50 AI Guardrails with 1 fast friendly API.项目地址: https://gitcode.com/GitHub_Trending/ga/gateway创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Portkey AI Gateway 实战指南：一套 API 统一路由 1600+ LLM、自动重试、负载均衡与 AI 守卫
Portkey AI Gateway 实战指南一套 API 统一路由 1600 LLM、自动重试、负载均衡与 AI 守卫【免费下载链接】gatewayA blazing fast AI Gateway with integrated guardrails. Route to 1,600 LLMs, 50 AI Guardrails with 1 fast friendly API.项目地址: https://gitcode.com/GitHub_Trending/ga/gateway本篇技术指南围绕开源项目 Portkey AI Gateway 的核心能力展开如何用一条命令在 2 分钟内启动网关通过 OpenAI 兼容的 SDK 统一接入数百家大模型如何使用 config 配置实现自动重试、fallback、负载均衡、条件路由与输入/输出守卫guardrails以及网关在安全、成本、可观测性与多模态、Realtime 等方向的架构设计。读完本文你将掌握基于该网关搭建高可用、可治理的 LLM 接入层的完整实战方案并了解其底层实现原理。项目定位一个轻量、可自托管的 AI 网关Portkey AI Gateway 是一个开源的 AI 网关AI GatewayREADME 将其定位为用一套快速且友好的 API将请求路由到 1600 语言、视觉、音频与图像模型轻量、开源、面向企业级生产环境集成时间可控制在 2 分钟以内。README 中给出的关键特征包括极快的转发延迟README 称 1ms与极小的体积README 称 122kb经过大规模生产验证README 称每日处理超过 100 亿 token企业级就绪增强的安全、规模扩展与自定义部署能力。以上数据均为 README 中的官方描述实际性能会随部署环境而异。值得注意的是当前仓库 package.json 中的版本为1.15.2README 顶部还预告了 Gateway 2.0Pre-Release——Portkey 的核心企业网关将随 2.0 版本合并入开源代码预发布分支可单独体验。从源码结构看网关核心位于 src/index.ts它基于 Hono 框架构建兼容 Node.js 与 Cloudflare Workersworkerd等运行时。src/index.ts中注册了/v1/chat/completions、/v1/completions、/v1/embeddings、/v1/images/generations、/v1/audio/speech、/v1/audio/transcriptions、/v1/audio/translations、/v1/messagesAnthropic 格式、/v1/files、/v1/batches、/v1/responses、/v1/fine_tuning/jobs、/v1/models等一整套 OpenAI/Anthropic 风格端点并用proxyHandler兜底处理其余/v1/*请求。这意味着你几乎可以把任意 LLM 请求原样交给网关由它负责协议转换与路由。2 分钟快速开始第一步本地启动网关README 给出的最快启动方式是一条npx命令需要本机已安装 Node.js 和 npmnpx portkey-ai/gateway启动后网关 API 地址为http://localhost:8787/v1网关控制台Gateway Console地址为http://localhost:8787/public/端口号与默认值的细节可以从 src/start-server.ts 中得到源码级确认默认端口为8787支持通过命令行参数--port覆盖支持--headless参数非 headless 模式下才会注册/public/与/public/logs的静态页面路由以及/log/stream的 SSE 日志流接口用于在浏览器中实时查看本地日志/v1/realtime路由通过 WebSocket 提供服务upgradeWebSocket(realTimeHandlerNode)用于接入 OpenAI 风格的 Realtime API。也可以从仓库源码构建后运行# 克隆仓库仓库地址用于说明 git clone 场景 git clone https://gitcode.com/GitHub_Trending/ga/gateway cd gateway npm i npm run build node build/start-server.js对应脚本定义在 package.json 的dev:nodetsx src/start-server.ts与start:nodenode build/start-server.js中。第二步发出第一个请求网关提供 OpenAI 兼容接口因此你既可以用 Portkey 官方 Python SDK也可以直接使用 OpenAI SDK、REST 调用。README 的 Python 示例# pip install -qU portkey-ai from portkey_ai import Portkey # OpenAI 兼容客户端 client Portkey( provideropenai, # 或 anthropic, bedrock, groq 等 Authorizationsk-*** # 提供方 API Key ) # 通过 AI Gateway 发起请求 client.chat.completions.create( messages[{role: user, content: Whats the weather like?}], modelgpt-4o-mini )provider参数决定请求被路由到哪家模型服务商。仓库 src/globals.ts 中的VALID_PROVIDERS数组列出了网关当前支持的全部 provider 标识包括openai、azure-openai、anthropic、bedrock、groq、google、vertex-ai、mistral-ai、together-ai、stability-ai、ollama、deepseek、zhipu、x-ai、oracle、sagemaker、cortex等上百个常量对应 src/providers 目录下同名的提供方实现每个目录通常包含api.ts、chatComplete.ts、complete.ts、embed.ts等文件。除 Python 外README 提到网关同样支持 JS、纯 REST、OpenAI SDK、LangChain、LlamaIndex、Autogen、CrewAI 等多种接入方式仓库 cookbook 目录中提供了大量可运行的集成示例例如 cookbook/integrations/vercel-ai.mdVercel AI SDK 接入、cookbook/integrations/langchain.ipynbLangChain 接入等。第三步在 Console 查看日志README 指出在 Gateway Consolehttp://localhost:8787/public/可以看到全部本地日志。从 src/start-server.ts 的实现看/log/stream通过 SSE 把日志实时推送给浏览器包含连接事件connected、心跳heartbeat等协议细节Cache-Control: no-cache与X-Accel-Buffering: no头确保日志不被缓冲、实时可见。路由与守卫用 Config 给请求附加可靠性策略README 明确指出网关中的Configs让你可以创建路由规则、增加可靠性配置并设置守卫guardrails。下面这段示例是 README 的核心演示同时用到了重试与输出守卫config { retry: {attempts: 5}, output_guardrails: [{ default.contains: {operator: none, words: [Apple]}, deny: True }] } # 将 config 挂到客户端 client client.with_options(configconfig) client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: Reply randomly with Apple or Bat}] ) # 由于守卫会拒绝所有包含 Apple 的回答最终总是返回 Bat # retry 配置则会在失败时最多重试 5 次。这段示例同时展示了网关两个核心机制retry自动重试retry.attempts指定最大重试次数README 示例为 5与 src/globals.ts 中的MAX_RETRIES 5一致。重试的底层实现在 src/handlers/retryHandler.ts 的retryRequest函数中值得关注的设计点默认重试状态码RETRY_STATUS_CODES [429, 500, 502, 503, 504]定义于 src/globals.ts即限流与常见的 5xx 服务端错误会触发重试请求级超时返回 408REQUEST_TIMEOUT_STATUS_CODE指数退避基于async-retry库实现randomize: false关闭随机抖动靠退避间隔错开重试请求避免网络过载尊重提供方重试头当响应为 429 且配置了followProviderRetry时网关会读取retry-after-ms、x-ms-retry-after-ms、retry-after头POSSIBLE_RETRY_STATUS_HEADERS按提供方建议的等待时间重试总重试时间上限MAX_RETRY_LIMIT_MS 60 * 100060 秒如果提供方要求的等待时间超过剩余预算网关会跳过本次重试直接返回错误连接级错误兜底遇到 DNS/连接失败ConnectTimeoutError返回 503其余未带 status 的错误返回 500保证任何情况下都能拿到结构化响应。配置层面的类型定义在 src/types/requestBody.ts 中字段类型说明attemptsnumber最大重试次数onStatusCodesnumber[]指定哪些 HTTP 状态码触发重试覆盖默认的 429/500/502/503/504useRetryAfterHeaderboolean是否使用提供方返回的 retry-after 等待时间output_guardrailsAI 守卫示例中的default.contains是网关内置的默认守卫插件之一。它对应的实现是 plugins/default/contains.ts插件从响应文本中统计命中的词foundWords与缺失的词missingWords按operator判定any命中任意一个词即通过all全部词都出现才通过none一个词都不出现才通过示例使用此模式因此任何包含 Apple 的输出都被拒绝。结合deny: True一旦守卫判定失败请求即被拦截。守卫的底层执行机制是把 config 中的input_guardrails/output_guardrails转换为 before/after 请求钩子hooks——src/handlers/handlerUtils.ts 中的convertHooksShorthand负责这一转换它会解析deny、on_fail、on_success、async、id等公共字段把剩余键包装成default.${checkId}形式的检查项最终挂到beforeRequestHooks/afterRequestHooks上执行。仓库的 plugins/default 目录内置了大量默认守卫例如contains、wordCount、sentenceCount、characterCount、regexMatch、regexReplace、jsonSchema、jwt、modelWhitelist、modelRules、validUrls、webhook、requiredMetadataKeys等并配套有 plugins/default/default.test.ts 单元测试。README 称共有 40 个预置守卫可选除内置插件外仓库还集成了多家第三方守卫供应商插件见 plugins 目录acuvity、aporia、azure内容安全/PII/受保护素材、bedrock、crowdstrike-aidr、exa、f5-guardrails、javelin、lasso、mistral、pangea、panw-prisma-airs、patronus、pillar、portkey、promptfoo、promptsecurity、qualifire、sydelabs、walledai等。哪些插件默认启用由 conf.example.json 中的plugins_enabled数组决定默认启用了default、portkey、aporia、sydelabs、pillar、patronus、pangea、promptsecurity、panw-prisma-airs、walledai。通过请求头发送 config除了 SDK 方式挂载 config网关还支持通过请求头传递配置x-portkey-*系列头前缀由 src/globals.ts 中的POWERED_BY portkey决定。constructConfigFromRequestHeaders位于 src/handlers/handlerUtils.ts会解析这些头包括x-portkey-api-key、x-portkey-provider、x-portkey-config、x-portkey-retry-count、x-portkey-cache、x-portkey-metadata、x-portkey-forward-headers、x-portkey-custom-host、x-portkey-request-timeout、x-portkey-strict-open-ai-compliance、x-portkey-virtual-key等以及各类提供方专属头Azure、AWS Bedrock、Vertex、SageMaker、Stability 等。这在不想改代码、只想临时指定路由策略的场景下非常实用。核心特性源码级解析README 把核心特性归纳为四类可靠路由、安全与准确、成本管理、协作与工作流。下面逐项展开。可靠路由Reliable RoutingREADME 列出的可靠路由能力包括Fallbacks故障回退请求失败时回退到另一个提供方或模型且可以指定触发回退的错误码。路由策略定义在 src/types/requestBody.ts 的StrategyModesloadbalance、fallback、single、conditional。回退逻辑在 src/handlers/handlerUtils.ts 的tryTargetsRecursively中fallback 模式下按顺序遍历targets只有当响应状态命中strategy.onStatusCodes或响应非 ok、或标记为网关异常x-portkey-gateway-exception: true时才继续尝试下一个目标Automatic Retries自动重试最多重试 5 次指数退避见上文 retry 解析Load Balancing负载均衡把请求按权重分发到多个 API Key 或多个提供方。selectProviderByWeight与tryTargetsRecursively的LOADBALANCE分支实现加权随机选择权重缺省为 1确保高可用与最优性能Request Timeouts请求超时可设置细粒度的请求超时超过时长的请求会被自动终止408 响应见retryHandler.ts的fetchWithTimeoutMulti-modal LLM Gateway多模态以统一的 OpenAI 签名调用视觉、音频TTS 与 STT、图像生成模型。这在 src/index.ts 的路由注册中可看到/v1/audio/speech、/v1/audio/transcriptions、/v1/audio/translations、/v1/images/generations、/v1/images/edits均有独立 handlerRealtime APIs实时接口通过内置的 WebSocket 服务器/v1/realtime接入 OpenAI 发布的 Realtime APINode 与 workerd 运行时各有实现src/handlers/realtimeHandlerNode.ts 与 src/handlers/realtimeHandler.ts。此外还有条件路由Conditional Routingstrategy.mode conditional时网关根据 metadata、请求参数或 URL 路径选择目标。实现位于 src/services/conditionalRouter.ts支持丰富的查询操作符$eq、$ne、$gt、$gte、$lt、$lte、$in、$nin、$regex以及逻辑组合$and/$or并可配置default目标作为兜底。条件路由配合 circuit breaker熔断等能力可以从源码中看到tryTargetsRecursively会过滤掉isOpen的异常目标。安全与准确Security AccuracyGuardrails守卫对 LLM 输入与输出做合规校验内置 40 预置守卫可自带守卫bring your own guardrails或选用多家合作供应商见上文插件列表Secure Key Management密钥管理既可用自己的 API Key也可按需动态生成虚拟 Keyx-portkey-virtual-key实现密钥不落盘、按需分发RBAC基于角色的访问控制对用户、工作空间与 API Key 做细粒度访问控制合规与数据隐私README 声明网关符合 SOC2、HIPAA、GDPR 与 CCPA 标准属 README 表述具体合规认证情况请以官方渠道为准。成本管理Cost ManagementSmart Caching智能缓存缓存 LLM 响应以降低成本、降低延迟支持简单缓存与语义缓存。本地内存缓存由 src/index.ts 中的memoryCache中间件与 src/handlers/services/cacheService.ts 实现配置conf.cache true即启用。此外 src/index.ts 还支持REDIS_CONNECTION_STRING环境变量Node 运行时下可切换到 Redis 缓存后端Usage Analytics用量分析监控请求量、延迟、成本与错误率网关在 src/handlers/services/logsService.ts 中记录每次请求的完整日志含缓存状态、重试次数、hook 链路 ID 等Provider Optimization根据用量模式与定价模型自动切换最经济的提供方README 标注为托管版与企业版能力。协作与工作流Collaboration WorkflowsAgents 支持与 Autogen、CrewAI、LangChain、LlamaIndex、Phidata、Control Flow 等流行 Agent 框架无缝集成也支持自定义 Agent。仓库 cookbook/integrations 下有大量对应 notebookPrompt Template Management通过统一的 prompt 游乐场创建、管理与版本化提示模板README 标注为托管版与企业版能力网关侧提供/v1/prompts/*端点见 src/index.ts。MCP GatewayMCP 服务器的统一控制面README 还介绍了独立的 MCP Gateway 能力为组织内的 MCPModel Context Protocol服务器提供集中控制平面认证Authentication网关层单一认证用户只需认证一次MCP 服务器收到的是已验证的请求访问控制Access Control控制哪些团队/用户可访问哪些服务器与工具可即时撤销访问可观测性Observability每次工具调用都会记录完整上下文谁调用了什么、参数、响应、延迟身份转发Identity Forwarding自动把用户身份邮箱、团队、角色转发给 MCP 服务器。它兼容 Claude Desktop、Cursor、VS Code 以及任何 MCP 兼容客户端。支持的提供方与 Agent 框架README 给出了一个提供方支持矩阵部分节选均支持流式提供方SupportStreamOpenAI✅✅Azure OpenAI✅✅Anyscale✅✅Google Gemini✅✅Anthropic✅✅Cohere✅✅Together AI✅✅Perplexity✅✅Mistral✅✅Nomic✅✅AI21✅✅Stability AI✅✅DeepInfra✅✅Ollama✅✅Novita AI✅✅完整清单以 src/globals.ts 的VALID_PROVIDERS与 src/providers 目录为准——从目录看当前仓库实际实现了 100 个提供方模块含azure-ai-inference、google-vertex-ai、sagemaker、x-ai、z-ai、oracle等README 称支持 45 提供方集成与 8 Agent 框架。值得注意的是 README 同时声称覆盖 1600 模型、200 模型完整列表可查这些数字属于项目方宣传口径实际以源码与官方文档为准。Agent 框架方面README 的表格显示 Autogen、CrewAI、LangChain、Phidata、LlamaIndex、Control Flow 及自建 Agent 均支持调用 200 LLM、高级路由、缓存、日志与追踪、可观测性、提示管理后几项标注为托管版能力。部署方式README 提供了丰富的部署选项详细步骤见 docs/installation-deployments.md此处摘要如下方式命令 / 说明npm / npxnpx portkey-ai/gateway需要 Node.jsBunbunx portkey-ai/gatewayNode.js Server克隆仓库 →npm i npm run build→node build/start-server.jsDockerdocker run --rm -p 8787:8787 portkeyai/gateway:latestDocker Composedocker compose up -d使用仓库内 docker-compose.yamlCloudflare Workersnpm run deploy基于 wrangler.toml 与 src/index.tsReplit一键部署详见 docs/deploy-on-replit.mdKubernetes / AWS EC2 / F5 App Stack / Supabase Functions / Fastly / Zeabur详见部署文档仓库根目录还提供了 deployment.yamlKubernetes 部署清单、Dockerfile 与 docker-compose.yaml。由于网关核心基于 Hono天然支持在 Node、workerdCloudflare Workers、lagon 等运行时上运行src/index.ts 中会按运行时跳过不必要的压缩中间件避免双重压缩并差异化管理 WebSocket 与静态页面。企业版与自托管扩展README 介绍的企业版私有部署在开源网关之上叠加了Secure Key Management基于角色的访问控制与用量追踪Simple Semantic Caching更快地服务重复查询并节省成本Access Control Inbound Rules控制哪些 IP 与地域可以连接你的部署PII Redaction自动从请求中移除敏感数据防止意外泄露SOC2、ISO、HIPAA、GDPR 合规README 表述专业支持与特性优先排期。企业版支持 AWS、Azure、GCP、OpenShift、Kubernetes 等平台的私有部署。总结与延伸阅读Portkey AI Gateway 的价值在于把接入多家 LLM 可靠路由 安全治理沉淀为一条可自托管的网关层对外提供 OpenAI 兼容 API对内通过configSDK 对象或x-portkey-*请求头声明式地编排重试、回退、负载均衡、条件路由与守卫并由插件体系plugins支撑可扩展的输入/输出检查。对于希望进一步上手的读者可以继续阅读docs/installation-deployments.md完整部署矩阵cookbook获取 Nvidia NIM、CrewAI 监控、LMSYS 模型对比、Vercel AI SDK 等实战 notebookconf.example.json网关配置示例插件启用、提供方凭证、限流与模型定价plugins/default内置守卫插件源码与 plugins/default/default.test.ts 测试用例src/handlers/retryHandler.ts 与 src/services/conditionalRouter.ts重试与条件路由的核心实现。整体来看该网关是一套API 兼容层 策略引擎 插件化守卫的三层架构适合作为企业统一 LLM 接入层的自托管底座。【免费下载链接】gatewayA blazing fast AI Gateway with integrated guardrails. Route to 1,600 LLMs, 50 AI Guardrails with 1 fast friendly API.项目地址: https://gitcode.com/GitHub_Trending/ga/gateway创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考