尧图网站建设 
在 Portkey AI Gateway 中使用 OpenAI SDK 调用 Prompt 模板从 Prompt Playground 到生产级 Chat Completion 的完整指南【免费下载链接】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/gatewayPortkey AI Gateway 提供了一致的 OpenAI 兼容 API并内置了可复用的 Prompt 模板Prompt Templates体系。本文基于仓库中 cookbook/use-cases/use-openai-sdk-with-portkey-prompt-templates.md 的实操流程完整演示在 Prompt Playground 创建模板 → 通过 Render API 获取模板详情 → 用 OpenAI SDK 发起 Chat Completion 请求的端到端链路并补充仓库源码级的原理剖析。读完本文你将掌握如何让团队所有成员共享同一份 Prompt 模板单一事实来源并在不改动业务代码的前提下随时切换提示词与超参数。为什么用 Prompt 模板把提示词变成团队的单一事实来源Portkey 的 Prompt Playground提示词游乐场允许你在无任何外部依赖的情况下测试和微调各种超参数temperature、max tokens、frequency penalty 等并将调优结果一键部署到生产环境。其核心价值在于版本化回滚Playground 会对每次保存的模型参数快照进行版本管理方便随时回滚团队协同所有成员使用同一份 Prompt 模板保证大家从同一个单一事实来源出发避免提示词散落在各个代码仓库和本地文件里运行时动态化模板中的{{变量}}会在请求时被替换为实际传入的内容一套模板即可覆盖海量业务场景。在本仓库的网关实现中Prompts 能力以路由形式暴露。在 src/index.ts 中可以看到/** * POST route for /v1/prompts/:id/completions. * Handles portkey prompt completions route */ app.post(/v1/prompts/*, requestValidator, (c) { if (c.req.url.endsWith(/v1/chat/completions)) { return chatCompletionsHandler(c); } else if (c.req.url.endsWith(/v1/completions)) { return completionsHandler(c); } // ... });这意味着网关原生支持把 Prompt 模板直接接到/v1/prompts/*路由上完成聊天补全而本文要讲的则是在客户端侧先渲染模板、再走标准 OpenAI SDK 的另一种灵活路径。第一步在 Prompt Playground 创建模板1.1 操作路径访问www.portkey.ai打开 Dashboard点击Prompts再点击Create按钮进入 Prompt Playground即可开始实验。在 Playground 中你可以针对不同 LLM 提供商反复试验提示词与超参数组合。以让 gpt-4 讲一个关于任意主题的儿童故事为例以下是文档作者最终确定的一组参数参数取值SystemYou are a very good storyteller who covers various topics for the kids. You narrate them in very intriguing and interesting ways. You tell the story in less than 3 paragraphs.UserTell me a story about {{topic}}Max Tokens512Temperature0.9Frequency Penalty-0.21.2 理解{{topic}}动态变量注意 User 角色内容中的{{topic}}Portkey 将其视为动态变量运行时可通过字符串替换。这意味着这个模板不只是写一个故事而是写任意主题的故事——把提示词从静态文本升级为可复用、可参数化的能力单元。调优满意后点击Save Prompt保存。Prompts 页面会列出所有已保存的模板及其对应的Prompt ID这个 ID 将在后续代码中被引用。1.3 从源码理解这些超参数的影响在网关的 OpenAI 提供商实现 src/providers/openai/chatComplete.ts 中可以看到这些超参数在网关侧的真实约束与默认值与模板中的取值相互印证max_tokens默认100最小值0——模板中的512会原样透传temperature默认1范围[0, 2]——模板中的0.9处于合法区间top_p默认1范围[0, 1]frequency_penalty范围[-2, 2]——模板中的-0.2属于鼓励重复一侧的轻微调节presence_penalty范围[-2, 2]模板未显式设置渲染结果中会补为0。这些参数在请求到达各提供商之前会经过 src/services/transformToProviderRequest.ts 的转换与校验getValue会对数值参数执行min/max钳制对缺失的必需参数填充默认值。因此从 Playground 渲染出的参数对象可以直接作为请求体使用网关会保证其符合目标提供商的规格。第二步通过 Render API 检索模板详情2.1 核心思路在代码编辑器中使用axios向 Portkey 的Render 端点发起POST请求把 Prompt ID 与变量值传过去即可拿到一份已经渲染好变量、可直接用于 Chat Completion的请求参数对象。Render 端点的结构为POST https://api.portkey.ai/v1/prompts/${PROMPT_ID}/render请求头需携带 Portkey API Key请求体传入模板中需要用到的变量。2.2 完整示例代码import axios from axios; const PROMPT_ID prompt-id; const PORTKEYAI_API_KEY api_key; const url https://api.portkey.ai/v1/prompts/${PROMPT_ID}/render; const headers { Content-Type: application/json, x-portkey-api-key: PORTKEYAI_API_KEY }; const data { variables: { topic: Tom and Jerry } }; let { data: { data: promptDetail } } await axios.post(url, data, { headers }); console.log(promptDetail);2.3 渲染返回的 promptDetail 结构控制台输出的promptDetail是一个标准的 OpenAI Chat Completion 请求参数对象{ model: gpt-4, n: 1, top_p: 1, max_tokens: 512, temperature: 0.9, presence_penalty: 0, frequency_penalty: -0.2, messages: [ { role: system, content: You are a very good storyteller who covers various topics for the kids. You narrate them in very intriguing and interesting ways. You tell the story in less than 3 paragraphs. }, { role: user, content: Tell me a story about Tom and Jerry } ] }可以观察到两个关键点变量已替换{{topic}}已被渲染为Tom and Jerry参数已补全模板未显式设置的n: 1、top_p: 1、presence_penalty: 0被自动填充说明模板系统与 OpenAI 参数语义完全对齐。由于该对象就是标准的 Chat Completion 请求体它可以被直接透传给任何 OpenAI 兼容客户端——这正是下一步通过 OpenAI SDK 调用能够无缝衔接的原因。从网关源码看/v1/chat/completions路由src/index.ts由chatCompletionsHandler处理该处理器会读取请求头中的路由配置并选择目标提供商进行转发见 src/handlers/chatCompletionsHandler.ts因此只要 SDK 把请求发到网关地址就能获得与直接调用 OpenAI 完全一致的体验。第三步通过 OpenAI SDK 发起 Chat Completion3.1 初始化 OpenAI 客户端导入所需库并创建 OpenAI 客户端实例关键在于把baseURL指向 Portkey 网关并通过defaultHeaders注入提供商、Portkey API Key 与虚拟密钥Virtual Keyimport OpenAI from openai; import { createHeaders, PORTKEY_GATEWAY_URL } from portkey-ai; const client new OpenAI({ apiKey: USES_VIRTUAL_KEY, baseURL: PORTKEY_GATEWAY_URL, defaultHeaders: createHeaders({ provider: openai, apiKey: ${PORTKEYAI_API_KEY}, virtualKey: ${OPENAI_VIRTUAL_KEY} }) });PORTKEY_GATEWAY_URL与createHeaders均来自portkey-ai官方 SDK用于统一改写 base URL 与请求头provider: openai指定目标提供商网关据此将 OpenAI 格式的请求体转换为对应提供商的格式virtualKey指向你在 Portkey Vault 中创建的虚拟密钥。虚拟密钥机制让你无需在业务代码中直接暴露各家 LLM 提供商的真实密钥也便于在网关侧统一做密钥轮换与权限管控。3.2 封装渲染 生成的完整流程将上一步的渲染逻辑封装为generateStory(topic)函数先渲染模板拿到promptDetail再调用client.chat.completions.create(promptDetail)最后返回首条消息内容let TomAndJerryStory await generateStory(Tom and Jerry); console.log(TomAndJerryStory); async function generateStory(topic) { const data { variables: { topic: String(topic) } }; let { data: { data: promptDetail } } await axios.post(url, data, { headers }); const chatCompletion await client.chat.completions.create(promptDetail); return chatCompletion.choices[0].message.content; }运行代码即可在控制台看到根据指定主题生成的故事In the heart of a bustling city, lived an eccentric cat named Tom and a witty little mouse named Jerry. Tom, always trying to catch Jerry, maneuvered himself th...(truncated)3.3 从源码看请求在网关侧的流转当 OpenAI SDK 将请求发送到网关的/v1/chat/completions时网关会经过如下链路可对照 src/handlers/handlerUtils.ts 中的tryPost与tryTargetsRecursively解析配置constructConfigFromRequestHeaders从请求头如x-portkey-provider、x-portkey-virtual-key等解析出路由配置请求转换transformToProviderRequest依据 src/providers/openai/chatComplete.ts 中的OpenAIChatCompleteConfig把请求参数映射为 OpenAI 格式model、messages、temperature、frequency_penalty等字段一一对应目标选择与重试tryTargetsRecursively支持single单目标、fallback故障回退、loadbalance加权负载均衡、conditional条件路由四种策略模式并配合retryHandler实现自动重试响应返回结果以 OpenAI 兼容格式返回 SDKchoices[0].message.content即生成的故事文本。这意味着你渲染出的promptDetail不仅适用于 OpenAI也可以借助网关路由到 Anthropic、Bedrock、Groq 等 1600 模型提供商——提示词与模型解耦这是模板体系在生产环境中的核心优势。Bonus使用 Portkey SDK 直接调用模板如果你使用的是官方portkey-ai客户端 SDK则无需手动调用 Render API。SDK 提供了与 OpenAI Chat Completion 签名相似的prompts.completions.create方法只需传入promptID与variables两个参数即可直接调用模板const promptCompletion await portkey.prompts.completions.create({ promptID: Your Prompt ID, variables: { topic: Tom and Jerry } });这与网关在 src/index.ts 中暴露的/v1/prompts/*路由语义一致传入 Prompt ID 与变量网关完成模板渲染与提供商路由。相比Render OpenAI SDK的两步走方案SDK 直调把渲染过程收敛到了网关内部代码更加简洁。完整代码一览将上述步骤整合为一份可直接运行的 Node.js 程序import axios from axios; import OpenAI from openai; import { createHeaders, PORTKEY_GATEWAY_URL } from portkey-ai; const PROMPT_ID xxxxxx; const PORTKEYAI_API_KEY xxxxx; const OPENAI_VIRTUAL_KEY xxxx; const url https://api.portkey.ai/v1/prompts/${PROMPT_ID}/render; const headers { Content-Type: application/json, x-portkey-api-key: PORTKEYAI_API_KEY }; const client new OpenAI({ apiKey: USES_VIRTUAL_KEY, baseURL: PORTKEY_GATEWAY_URL, defaultHeaders: createHeaders({ provider: openai, apiKey: ${PORTKEYAI_API_KEY}, virtualKey: ${OPENAI_VIRTUAL_KEY} }) }); let TomAndJerryStory await generateStory(Tom and Jerry); console.log(TomAndJerryStory); async function generateStory(topic) { const data { variables: { topic: String(topic) } }; let { data: { data: promptDetail } } await axios.post(url, data, { headers }); const chatCompletion await client.chat.completions.create(promptDetail); return chatCompletion.choices[0].message.content; }总结与延伸至此我们已经完成了一个完整的 Node.js 程序通过 Prompt ID 从 Prompt Playground 检索模板详情再借助 OpenAI SDK 成功生成指定主题的故事。这套方案的价值在于提示词与代码解耦Prompt 模板在 Playground 中维护代码只依赖 Prompt ID调整提示词无需发布代码团队共享单一事实来源所有成员引用同一模板提示词版本可回滚、可审计多提供商复用渲染出的promptDetail是标准 OpenAI 格式可经网关转发到任意受支持的 LLM参考仓库 README.md 中列出的 1600 模型路由能力真正做到专注提升提示词质量运行时按需引用模型。如果想进一步探索可以继续阅读仓库中其他相关 cookbook如 cookbook/getting-started/writing-your-first-gateway-config.md、cookbook/getting-started/automatic-retries-on-failures.md了解网关配置、自动重试等与模板体系配合使用的能力。【免费下载链接】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 中使用 OpenAI SDK 调用 Prompt 模板：从 Prompt Playground 到生产级 Chat Completion 的完整指南
在 Portkey AI Gateway 中使用 OpenAI SDK 调用 Prompt 模板从 Prompt Playground 到生产级 Chat Completion 的完整指南【免费下载链接】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/gatewayPortkey AI Gateway 提供了一致的 OpenAI 兼容 API并内置了可复用的 Prompt 模板Prompt Templates体系。本文基于仓库中 cookbook/use-cases/use-openai-sdk-with-portkey-prompt-templates.md 的实操流程完整演示在 Prompt Playground 创建模板 → 通过 Render API 获取模板详情 → 用 OpenAI SDK 发起 Chat Completion 请求的端到端链路并补充仓库源码级的原理剖析。读完本文你将掌握如何让团队所有成员共享同一份 Prompt 模板单一事实来源并在不改动业务代码的前提下随时切换提示词与超参数。为什么用 Prompt 模板把提示词变成团队的单一事实来源Portkey 的 Prompt Playground提示词游乐场允许你在无任何外部依赖的情况下测试和微调各种超参数temperature、max tokens、frequency penalty 等并将调优结果一键部署到生产环境。其核心价值在于版本化回滚Playground 会对每次保存的模型参数快照进行版本管理方便随时回滚团队协同所有成员使用同一份 Prompt 模板保证大家从同一个单一事实来源出发避免提示词散落在各个代码仓库和本地文件里运行时动态化模板中的{{变量}}会在请求时被替换为实际传入的内容一套模板即可覆盖海量业务场景。在本仓库的网关实现中Prompts 能力以路由形式暴露。在 src/index.ts 中可以看到/** * POST route for /v1/prompts/:id/completions. * Handles portkey prompt completions route */ app.post(/v1/prompts/*, requestValidator, (c) { if (c.req.url.endsWith(/v1/chat/completions)) { return chatCompletionsHandler(c); } else if (c.req.url.endsWith(/v1/completions)) { return completionsHandler(c); } // ... });这意味着网关原生支持把 Prompt 模板直接接到/v1/prompts/*路由上完成聊天补全而本文要讲的则是在客户端侧先渲染模板、再走标准 OpenAI SDK 的另一种灵活路径。第一步在 Prompt Playground 创建模板1.1 操作路径访问www.portkey.ai打开 Dashboard点击Prompts再点击Create按钮进入 Prompt Playground即可开始实验。在 Playground 中你可以针对不同 LLM 提供商反复试验提示词与超参数组合。以让 gpt-4 讲一个关于任意主题的儿童故事为例以下是文档作者最终确定的一组参数参数取值SystemYou are a very good storyteller who covers various topics for the kids. You narrate them in very intriguing and interesting ways. You tell the story in less than 3 paragraphs.UserTell me a story about {{topic}}Max Tokens512Temperature0.9Frequency Penalty-0.21.2 理解{{topic}}动态变量注意 User 角色内容中的{{topic}}Portkey 将其视为动态变量运行时可通过字符串替换。这意味着这个模板不只是写一个故事而是写任意主题的故事——把提示词从静态文本升级为可复用、可参数化的能力单元。调优满意后点击Save Prompt保存。Prompts 页面会列出所有已保存的模板及其对应的Prompt ID这个 ID 将在后续代码中被引用。1.3 从源码理解这些超参数的影响在网关的 OpenAI 提供商实现 src/providers/openai/chatComplete.ts 中可以看到这些超参数在网关侧的真实约束与默认值与模板中的取值相互印证max_tokens默认100最小值0——模板中的512会原样透传temperature默认1范围[0, 2]——模板中的0.9处于合法区间top_p默认1范围[0, 1]frequency_penalty范围[-2, 2]——模板中的-0.2属于鼓励重复一侧的轻微调节presence_penalty范围[-2, 2]模板未显式设置渲染结果中会补为0。这些参数在请求到达各提供商之前会经过 src/services/transformToProviderRequest.ts 的转换与校验getValue会对数值参数执行min/max钳制对缺失的必需参数填充默认值。因此从 Playground 渲染出的参数对象可以直接作为请求体使用网关会保证其符合目标提供商的规格。第二步通过 Render API 检索模板详情2.1 核心思路在代码编辑器中使用axios向 Portkey 的Render 端点发起POST请求把 Prompt ID 与变量值传过去即可拿到一份已经渲染好变量、可直接用于 Chat Completion的请求参数对象。Render 端点的结构为POST https://api.portkey.ai/v1/prompts/${PROMPT_ID}/render请求头需携带 Portkey API Key请求体传入模板中需要用到的变量。2.2 完整示例代码import axios from axios; const PROMPT_ID prompt-id; const PORTKEYAI_API_KEY api_key; const url https://api.portkey.ai/v1/prompts/${PROMPT_ID}/render; const headers { Content-Type: application/json, x-portkey-api-key: PORTKEYAI_API_KEY }; const data { variables: { topic: Tom and Jerry } }; let { data: { data: promptDetail } } await axios.post(url, data, { headers }); console.log(promptDetail);2.3 渲染返回的 promptDetail 结构控制台输出的promptDetail是一个标准的 OpenAI Chat Completion 请求参数对象{ model: gpt-4, n: 1, top_p: 1, max_tokens: 512, temperature: 0.9, presence_penalty: 0, frequency_penalty: -0.2, messages: [ { role: system, content: You are a very good storyteller who covers various topics for the kids. You narrate them in very intriguing and interesting ways. You tell the story in less than 3 paragraphs. }, { role: user, content: Tell me a story about Tom and Jerry } ] }可以观察到两个关键点变量已替换{{topic}}已被渲染为Tom and Jerry参数已补全模板未显式设置的n: 1、top_p: 1、presence_penalty: 0被自动填充说明模板系统与 OpenAI 参数语义完全对齐。由于该对象就是标准的 Chat Completion 请求体它可以被直接透传给任何 OpenAI 兼容客户端——这正是下一步通过 OpenAI SDK 调用能够无缝衔接的原因。从网关源码看/v1/chat/completions路由src/index.ts由chatCompletionsHandler处理该处理器会读取请求头中的路由配置并选择目标提供商进行转发见 src/handlers/chatCompletionsHandler.ts因此只要 SDK 把请求发到网关地址就能获得与直接调用 OpenAI 完全一致的体验。第三步通过 OpenAI SDK 发起 Chat Completion3.1 初始化 OpenAI 客户端导入所需库并创建 OpenAI 客户端实例关键在于把baseURL指向 Portkey 网关并通过defaultHeaders注入提供商、Portkey API Key 与虚拟密钥Virtual Keyimport OpenAI from openai; import { createHeaders, PORTKEY_GATEWAY_URL } from portkey-ai; const client new OpenAI({ apiKey: USES_VIRTUAL_KEY, baseURL: PORTKEY_GATEWAY_URL, defaultHeaders: createHeaders({ provider: openai, apiKey: ${PORTKEYAI_API_KEY}, virtualKey: ${OPENAI_VIRTUAL_KEY} }) });PORTKEY_GATEWAY_URL与createHeaders均来自portkey-ai官方 SDK用于统一改写 base URL 与请求头provider: openai指定目标提供商网关据此将 OpenAI 格式的请求体转换为对应提供商的格式virtualKey指向你在 Portkey Vault 中创建的虚拟密钥。虚拟密钥机制让你无需在业务代码中直接暴露各家 LLM 提供商的真实密钥也便于在网关侧统一做密钥轮换与权限管控。3.2 封装渲染 生成的完整流程将上一步的渲染逻辑封装为generateStory(topic)函数先渲染模板拿到promptDetail再调用client.chat.completions.create(promptDetail)最后返回首条消息内容let TomAndJerryStory await generateStory(Tom and Jerry); console.log(TomAndJerryStory); async function generateStory(topic) { const data { variables: { topic: String(topic) } }; let { data: { data: promptDetail } } await axios.post(url, data, { headers }); const chatCompletion await client.chat.completions.create(promptDetail); return chatCompletion.choices[0].message.content; }运行代码即可在控制台看到根据指定主题生成的故事In the heart of a bustling city, lived an eccentric cat named Tom and a witty little mouse named Jerry. Tom, always trying to catch Jerry, maneuvered himself th...(truncated)3.3 从源码看请求在网关侧的流转当 OpenAI SDK 将请求发送到网关的/v1/chat/completions时网关会经过如下链路可对照 src/handlers/handlerUtils.ts 中的tryPost与tryTargetsRecursively解析配置constructConfigFromRequestHeaders从请求头如x-portkey-provider、x-portkey-virtual-key等解析出路由配置请求转换transformToProviderRequest依据 src/providers/openai/chatComplete.ts 中的OpenAIChatCompleteConfig把请求参数映射为 OpenAI 格式model、messages、temperature、frequency_penalty等字段一一对应目标选择与重试tryTargetsRecursively支持single单目标、fallback故障回退、loadbalance加权负载均衡、conditional条件路由四种策略模式并配合retryHandler实现自动重试响应返回结果以 OpenAI 兼容格式返回 SDKchoices[0].message.content即生成的故事文本。这意味着你渲染出的promptDetail不仅适用于 OpenAI也可以借助网关路由到 Anthropic、Bedrock、Groq 等 1600 模型提供商——提示词与模型解耦这是模板体系在生产环境中的核心优势。Bonus使用 Portkey SDK 直接调用模板如果你使用的是官方portkey-ai客户端 SDK则无需手动调用 Render API。SDK 提供了与 OpenAI Chat Completion 签名相似的prompts.completions.create方法只需传入promptID与variables两个参数即可直接调用模板const promptCompletion await portkey.prompts.completions.create({ promptID: Your Prompt ID, variables: { topic: Tom and Jerry } });这与网关在 src/index.ts 中暴露的/v1/prompts/*路由语义一致传入 Prompt ID 与变量网关完成模板渲染与提供商路由。相比Render OpenAI SDK的两步走方案SDK 直调把渲染过程收敛到了网关内部代码更加简洁。完整代码一览将上述步骤整合为一份可直接运行的 Node.js 程序import axios from axios; import OpenAI from openai; import { createHeaders, PORTKEY_GATEWAY_URL } from portkey-ai; const PROMPT_ID xxxxxx; const PORTKEYAI_API_KEY xxxxx; const OPENAI_VIRTUAL_KEY xxxx; const url https://api.portkey.ai/v1/prompts/${PROMPT_ID}/render; const headers { Content-Type: application/json, x-portkey-api-key: PORTKEYAI_API_KEY }; const client new OpenAI({ apiKey: USES_VIRTUAL_KEY, baseURL: PORTKEY_GATEWAY_URL, defaultHeaders: createHeaders({ provider: openai, apiKey: ${PORTKEYAI_API_KEY}, virtualKey: ${OPENAI_VIRTUAL_KEY} }) }); let TomAndJerryStory await generateStory(Tom and Jerry); console.log(TomAndJerryStory); async function generateStory(topic) { const data { variables: { topic: String(topic) } }; let { data: { data: promptDetail } } await axios.post(url, data, { headers }); const chatCompletion await client.chat.completions.create(promptDetail); return chatCompletion.choices[0].message.content; }总结与延伸至此我们已经完成了一个完整的 Node.js 程序通过 Prompt ID 从 Prompt Playground 检索模板详情再借助 OpenAI SDK 成功生成指定主题的故事。这套方案的价值在于提示词与代码解耦Prompt 模板在 Playground 中维护代码只依赖 Prompt ID调整提示词无需发布代码团队共享单一事实来源所有成员引用同一模板提示词版本可回滚、可审计多提供商复用渲染出的promptDetail是标准 OpenAI 格式可经网关转发到任意受支持的 LLM参考仓库 README.md 中列出的 1600 模型路由能力真正做到专注提升提示词质量运行时按需引用模型。如果想进一步探索可以继续阅读仓库中其他相关 cookbook如 cookbook/getting-started/writing-your-first-gateway-config.md、cookbook/getting-started/automatic-retries-on-failures.md了解网关配置、自动重试等与模板体系配合使用的能力。【免费下载链接】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），仅供参考