ToolJet 集成 Portkey AI 网关：配置数据源并调用四种 LLM 操作

ToolJet 集成 Portkey AI 网关配置数据源并调用四种 LLM 操作【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJetToolJet 通过 Marketplace 提供 Portkey 插件将 Portkey 的 LMOps 平台能力接入内部工具构建流程支持文本补全Completion、对话补全Chat、提示词补全Prompt Completion与向量嵌入Create Embedding四类生成式 AI 操作。本指南完整讲解该插件的连接配置、四种操作的参数与响应结构并结合仓库中的插件源码portkey 插件目录剖析其底层调用链与默认值帮助你快速在 ToolJet 中搭建可维护、可迭代的 AI 功能。前置准备启用并安装 Marketplace 插件在连接 Portkey 之前需要先完成 ToolJet Marketplace 插件的启用与安装流程详见 Marketplace 使用指南。其核心步骤为启用 Marketplace 特性在 ToolJet 的.env文件中加入环境变量ENABLE_MARKETPLACE_FEATUREtrue对应环境变量说明见 setup/env-vars本地运行时需先构建 marketplace 再启动服务器。安装插件以管理员身份登录点击仪表盘左下角的设置图标进入Marketplace页面在Marketplace标签页中找到 Portkey 卡片并点击Install安装完成后状态变为Installed。配置数据源在仪表盘Data sources标签页滚动到Plugins区域即可看到已安装的 Portkey 插件并进行连接配置配置成功后在 Query Panel 新建查询时即可选用该数据源。Connection连接 Portkey 数据源进入 Portkey 数据源配置页后需要填写以下凭据配置项是否必填说明API Key必填你的 Portkey API Key。可参考 Portkey 官方 API 认证文档中Obtaining your API Key一节获取Default Virtual Key默认虚拟密钥可选你的默认 Portkey Virtual Key。可参考 Portkey 官方文档中Creating Virtual Keys一节创建与获取Config可选你的默认 Portkey 配置如路由、重试、缓存等网关策略Gateway URL可选你的默认 Portkey Gateway URL获取方式同 API Key 的认证文档从插件源码 manifest.json 可以印证这一表单结构apiKey与virtualKey字段的type均为password且标记encrypted: true服务端加密存储不会明文落库config与gatewayUrl为普通文本输入required数组中仅有apiKey与文档中的必填/可选关系完全一致。四个字段均提供了helpText在界面上内嵌跳转到 Portkey 官方文档的说明链接。在底层插件通过官方 SDK 建立连接。看 lib/index.ts 中的getConnection方法async getConnection(sourceOptions: SourceOptions): PromisePortKeyAi.Portkey { const { apiKey, virtualKey, config } sourceOptions; const creds { apiKey, virtualKey }; if (config) { creds[config] typeof config string ? JSON.parse(config) : null; } return new PortKeyAi.Portkey(creds); }即用apiKey、可选的virtualKey以及按 JSON 解析后的config构造portkey-ai客户端实例。此外插件实现了testConnectionlib/index.ts点击Test connection按钮时插件会调用portkey.models.list()拉取模型列表若返回data字段存在则判定连接成功否则抛出Connection could not be established错误。支持的操作总览Portkey 在 ToolJet 中支持以下四种操作与 operations.json 中operation下拉选项一一对应CompletioncompletionChatchatPrompt Completionprompt_completionCreate Embeddingcreate_embedding插件入口run方法lib/index.ts根据queryOptions.operation用 switch 分发到对应的实现函数若传入非法的操作值会抛出Query could not be completed与Invalid operation错误。此外四种操作都支持两个可选的查询级覆盖项Config本次请求使用的配置项覆盖数据源级别的默认配置Virtual Key本次请求使用的特定虚拟密钥覆盖数据源级别的默认 Virtual Key。源码中lib/index.ts会先检查查询选项中是否携带virtualKey或config有则临时替换到sourceOptions上再建立连接实现数据源默认值 单次查询覆盖的分层配置模式。Completion文本补全该操作根据给定的提示词prompt生成文本补全。参数说明参数说明Prompt用于生成补全的输入文本Model要使用的 AI 模型Max Tokens生成的最大 token 数界面提示取值范围 1–2048Temperature控制输出的随机性界面提示取值范围 0–1Stop Sequences遇到这些序列时 API 将停止继续生成 tokenMetadata请求的附加元数据Other Parameters请求中要包含的其他参数从 portkey_operations.ts 的实现看该操作最终调用portkey.completions.create()。值得注意的默认值与输入归一化逻辑model缺省时使用davinci-002temperature若以字符串传入会parseFloat转换默认1max_tokens若以字符串传入会parseInt转换默认256stop_sequences若以逗号分隔的字符串传入会被split(,)拆成数组metadata通过safeParseJSON见 utils.ts安全解析解析失败时回退为空对象同时作为请求体与 SDK 请求选项传入。响应示例{ id: cmpl-9vNUfM8OP0SwSqXcnPwkqzR7ep8Sy, object: text_completion, created: 1723462033, model: gpt-3.5-turbo-instruct, choices: [ { text: nnExperience the perfect brew at Bean There., index: 0, logprobs: null, finish_reason: stop } ], usage: { prompt_tokens: 13, completion_tokens: 10, total_tokens: 23 } }响应中的choices[0].text即生成的补全内容usage字段记录本次调用的 token 消耗可用于成本统计与限流设计。Chat对话补全该操作基于一系列消息messages生成对话补全适合构建多轮对话式 AI 功能。参数说明参数说明Messages表示对话的消息对象数组Model要使用的 AI 模型Max Tokens生成的最大 token 数Temperature控制输出的随机性Stop Sequence遇到这些序列时 API 将停止继续生成 tokenMetadata请求的附加元数据Other Parameters请求中要包含的其他参数messages参数在界面上的占位格式为[{role: user, content: Hello}, {role: assistant, content: Hi}]见 operations.json即以rolecontent组成的对话历史数组。实现层面portkey_operations.ts调用portkey.chat.completions.create()其中messages若以字符串传入会JSON.parse解析为数组默认模型为gpt-3.5-turbotemperature默认1max_tokens默认256与 Completion 相同stop_sequences支持逗号分隔字符串拆分为数组metadata经safeParseJSON处理并同时作用于请求体与 SDK 选项。响应示例{ id: chatcmpl-9vNIlfllXOPEmroKFajK2nlJHzhXA, object: chat.completion, created: 1723461295, model: gpt-3.5-turbo-0125, choices: [ { index: 0, message: { role: assistant, content: The capital of France is Paris., refusal: null }, logprobs: null, finish_reason: stop } ], usage: { prompt_tokens: 24, completion_tokens: 7, total_tokens: 31 }, system_fingerprint: null }对话结果位于choices[0].message.content。在 ToolJet 中可将上一轮响应回填到messages数组里实现多轮对话状态累积。Prompt Completion提示词补全该操作基于 Portkey 中预先定义好的提示词prompt生成补全。提示词模板托管在 Portkey 侧可在团队内复用并集中维护因此调用方只需引用Prompt ID并传入变量即可。参数说明参数说明Prompt ID要使用的预定义提示词的 IDVariables提示词中要使用的变量Parameters提示词补全的附加参数Metadata请求的附加元数据实现上portkey_operations.ts调用portkey.prompts.completions.create()请求体由四部分拼接而成const data await portkey.prompts.completions.create( { promptID: promptId, variables: typeof variables string ? JSON.parse(variables) : variables || null, ...JSON.parse(typeof options.prompt_parameters string ? options.prompt_parameters : {}), ...JSON.parse(typeof options.metadata string ? options.metadata : {}), }, JSON.parse(typeof options.metadata string ? options.metadata : {}) );即promptID、解析后的variables、prompt_parameters展开后的字段以及metadata展开后的字段共同构成最终请求体metadata同时作为 SDK 请求选项传入。Variables与Parameters均需以 JSON 形式填写。响应示例底层仍返回标准 chat completion 结构{ id: chatcmpl-9w6D8jZciWVf1DzkgqNZK14KUvA4d, object: chat.completion, created: 1723633926, model: gpt-4o-mini-2024-07-18, choices: [ { index: 0, message: { role: assistant, content: The Industrial Revolution, starting in the late 18th century, transformed production from hand methods to machine-based processes, introducing new manufacturing techniques, steam power, and machine tools. It marked a shift from bio-fuels to coal, with the textile industry leading the way. This period resulted in significant population growth, increased average income, and improved living standards., refusal: null }, logprobs: null, finish_reason: stop } ], usage: { prompt_tokens: 145, completion_tokens: 71, total_tokens: 216 }, system_fingerprint: fp_48196bc67a }Create Embedding创建向量嵌入该操作为给定的输入文本创建向量嵌入embedding可用于语义检索、知识库匹配、文本相似度计算等场景。参数说明参数说明Input要创建嵌入的输入文本Model用于创建嵌入的 AI 模型Metadata请求的附加元数据实现上portkey_operations.ts调用portkey.embeddings.create()将model、input与解析后的metadata合并进请求体。与前三类操作不同Embedding 操作没有模型与 token 的默认值兜底需要显式填写model与input。响应示例{ object: list, data: [ { object: embedding, index: 0, embedding: [ -0.02083237, -0.016892163, -0.0045676464, -0.05084554, -0.025968939, 0.029597048, 0.029987168, 0.02907689, 0.0105982395, -0.024356445, -0.00935636, 0.0066352785, 0.034018397, -0.042002838, 0.03856979, -0.014681488, ..., 0.024707552 ] } ], model: text-embedding-3-small, usage: { prompt_tokens: 9, total_tokens: 9 } }data[0].embedding为高维浮点向量数组示例省略了中间元素model字段回显所使用的嵌入模型。错误处理与调用链小结四种操作的实现函数均采用统一的 try/catch 包裹如 portkey_operations.ts} catch (error) { return { error: error?.message, statusCode: error?.response?.status, }; }当 Portkey API 调用失败时返回体携带error错误消息与statusCodeHTTP 状态码便于在 ToolJet 查询结果面板中定位问题入口层若捕获到未处理异常则统一包装为Query could not be completed的QueryError。完整的请求链路可概括为用户在 Query Panel 选择 Portkey 数据源与操作类型填写参数UI 字段定义见 operations.json插件run方法根据operation分发到对应实现lib/index.tsgetConnection以 API Key / Virtual Key / Config 构造portkey-ai客户端lib/index.ts各操作函数调用 SDK 的completions.create、chat.completions.create、prompts.completions.create或embeddings.create返回结果以{ status: ok, data: result }形式回传给查询面板。结语通过本指南你可以完成 Portkey 数据源在 ToolJet 中的连接配置并在应用查询中直接使用文本补全、对话补全、提示词补全与向量嵌入四类能力。得益于 Portkey 的 AI 网关能力虚拟密钥管理、统一配置与可观测性团队可以在 ToolJet 中以数据源级默认值 查询级覆盖的方式统一治理多个 LLM 提供方从而快速开发、发布、维护并迭代生成式 AI 功能。插件源码与类型定义位于 marketplace/plugins/portkey/lib可进一步阅读index.ts、portkey_operations.ts、types.ts与manifest.json了解全部实现细节。【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考