Genkit JS 开发指南：从快速入门到结构化输出、流式生成、工具调用与中断机制
【免费下载链接】genkitOpen-source framework for building agentic apps in JavaScript, Go, Dart, and Python, built and used in production by Google项目地址: https://gitcode.com/GitHub_Trending/ge/genkit
Genkit 是 Google 开源并已在生产环境中使用的 AI 应用框架（同时提供 JavaScript、Go、Dart、Python 实现），本文聚焦其JavaScript 库的 API 参考文档（仓库 js/index.typedoc.md），系统讲解从环境搭建、首个生成请求，到结构化输出、流式生成、工具调用（Function Calling）、人工介入中断（Interrupts）、Dotprompt 提示词管理、Flow 工作流与模型中间件等核心能力。读完本文，你将掌握 Genkit JS 的完整上手路径，并能够结合仓库源码理解其底层实现机制，直接在自己的项目中落地可运行的 AI 应用。
一、快速开始：环境搭建与首个生成请求
Genkit 是面向 AI 驱动应用的开源框架，其 JS 库的 API 参考文档为js/index.typedoc.md，对应的源码位于 js/genkit 与 js/ai、js/core 三个包中。安装 Genkit 依赖非常简单，只需两个步骤：
genkit—— 框架核心能力包；- 一个模型插件，例如使用 Google AI Gemini 模型的
@genkit-ai/google-genai。
在项目目录下执行：
npm install genkit @genkit-ai/google-genai随后配置 API 密钥（以 Google AI 为例）：
export GOOGLE_API_KEY=your-api-key接着发起第一个生成请求：
import { genkit } from 'genkit'; import { googleAI } from '@genkit-ai/google-genai'; const ai = genkit({ plugins: [googleAI()] }); const { text } = await ai.generate({ model: googleAI.model('gemini-flash-latest'), prompt: 'Why is Genkit awesome?', }); console.log(text);从源码看，js/genkit/src/index.ts 将Genkit类、genkit()工厂函数及GenkitOptions类型作为主入口导出；Genkit类封装了Registry（注册表，统一管理 actions、flows、tools 等组件）、ReflectionServer（反射服务器，暴露注册表检查与 action 执行 API）与FlowServer（将 flow 暴露为 HTTP 端点），详见 js/genkit/src/genkit.ts。GenkitOptions支持plugins、model（默认模型）、promptDir（dotprompt 目录，设为null可禁用自动加载）、context、name、clientHeader等配置项，见 js/genkit/src/genkit.ts。特别值得注意的是，Genkit构造函数在开发环境（isDevEnv()）下会自动启动 ReflectionServer，这正是 Genkit CLI 与开发者工具能够动态发现 actions 的基础。
二、包体系与子路径导入
js/index.typedoc.md以表格形式列出了当前仓库中全部 JS 包，每个包对应一个独立模块文档：
| 包名 | 说明 |
|---|---|
genkit | 核心框架——生成、flows、工具、提示词、流式等 |
@genkit-ai/google-genai | Google AI（Gemini）模型插件 |
@genkit-ai/vertexai | Vertex AI 模型插件 |
@genkit-ai/firebase | Firebase 集成（认证、Firestore、Cloud Functions） |
@genkit-ai/express | 将 flows 作为 Express 端点提供 |
@genkit-ai/google-cloud | Google Cloud 监控与遥测 |
@genkit-ai/next | Next.js 集成 |
@genkit-ai/checks | Google Checks 安全评估插件 |
@genkit-ai/dev-local-vectorstore | 本地向量库（开发用） |
@genkit-ai/evaluators | 内置评估器，测试 AI 输出质量 |
@genkit-ai/ollama | Ollama 本地模型插件 |
@genkit-ai/chroma | ChromaDB 向量库插件 |
@genkit-ai/pinecone | Pinecone 向量库插件 |
@genkit-ai/mcp | Model Context Protocol（MCP）插件 |
@genkit-ai/anthropic | Anthropic（Claude）模型插件 |
@genkit-ai/compat-oai | OpenAI 兼容模型插件 |
@genkit-ai/fetch | 插件用 HTTP fetch 工具 |
@genkit-ai/middleware | 模型中间件插件（retry、caching 等） |
@genkit-ai/a2ui | A2UI（Agent-to-UI）流式生成式 UI 插件 |
genkit主包还提供针对具体功能的子路径导入，便于按需引入、优化打包体积：
| 导入路径 | 用途 |
|---|---|
genkit | 主入口——Genkit类、generate、defineFlow、defineTool、schemas、types |
genkit/beta | Beta 特性，包括中断（defineInterrupt） |
genkit/beta/client | 客户端辅助函数（runFlow、streamFlow） |
genkit/model/middleware | 模型中间件（retry、fallback、augmentWithContext等） |
genkit/plugin | 插件编写工具（model、embedder、retriever等） |
genkit/model | 模型类型与辅助函数 |
genkit/embedder | Embedder 类型 |
genkit/retriever | Retriever 与 Indexer 类型 |
genkit/reranker | Reranker 类型 |
genkit/evaluator | Evaluator 类型 |
genkit/tool | 工具类型 |
genkit/schema | Schema 工具 |
以genkit/beta为例，js/genkit/src/beta.ts 从genkit主包扩展出了GenkitBeta类、Session、InMemorySessionStore、FileSessionStore、defineInterrupt相关类型以及diff/applyPatch（JSON Patch 工具）等 Beta 能力，同时保留了genkit主入口的全部导出。
三、核心特性一：结构化输出（Structured Output）
通过 Zod schema 可以生成强类型、经过 schema 校验的结构化输出。Zod schema 由genkit包直接导出（import { genkit, z } from 'genkit'），无需额外安装：
import { genkit, z } from 'genkit'; import { googleAI } from '@genkit-ai/google-genai'; const ai = genkit({ plugins: [googleAI()] }); const RecipeSchema = z.object({ title: z.string(), ingredients: z.array(z.string()), instructions: z.array(z.string()), }); const { output } = await ai.generate({ model: googleAI.model('gemini-flash-latest'), prompt: 'Invent a new pasta recipe', output: { schema: RecipeSchema }, }); console.log(output?.title); // fully typed当output.schema提供后，output字段会严格匹配RecipeSchema的类型定义，获得完整 TypeScript 类型推导。这与genkit包中的defineSchema/defineJsonSchema（js/genkit/src/genkit.ts）机制一致：schema 可注册到 registry 中，并在 prompt 里按名称引用，从而在提示词与代码之间复用统一的 schema 定义。
四、核心特性二：流式生成（Streaming）
使用generateStream可以实时接收模型输出流，逐块（chunk）处理文本：
const { response, stream } = ai.generateStream({ model: googleAI.model('gemini-flash-latest'), prompt: 'Write a short story about a robot', }); for await (const chunk of stream) { process.stdout.write(chunk.text); }generateStream返回的stream是异步可迭代对象，每个 chunk 暴露text字段；response为最终的完整响应对象。流式输出常用于打字机效果、长文本生成与进度反馈场景。此外，GenerateOptions还支持onChunk回调（见 js/ai/src/generate.ts），模型流式生成过程中每个 chunk 都会触发该回调，可用于在流式场景中记录日志或更新 UI 状态。
五、核心特性三：工具调用（Function Calling）
通过ai.defineTool定义工具，模型即可在生成过程中自动调用，以访问外部数据或执行动作：
const getWeather = ai.defineTool( { name: 'getWeather', description: 'Gets the current weather for a given city', inputSchema: z.object({ city: z.string() }), outputSchema: z.object({ temperature: z.number(), condition: z.string() }), }, async ({ city }) => { // your implementation here return { temperature: 72, condition: 'sunny' }; } ); const { text } = await ai.generate({ model: googleAI.model('gemini-flash-latest'), prompt: 'What should I wear in Tokyo today?', tools: [getWeather], });工具的inputSchema/outputSchema不仅提供类型安全，还会在运行时对输入输出做校验。Genkit.defineTool底层委托给@genkit-ai/ai的defineTool并将工具注册到 registry（js/genkit/src/genkit.ts），因此工具可以按名称或引用传入tools数组。GenerateOptions.tools支持传注册的工具名或 action 值（js/ai/src/generate.ts），maxTurns控制单次generate调用中工具调用迭代的最大轮数（默认 5，见 js/ai/src/generate.ts）。若希望手动处理工具调用而非自动解析，可设置returnToolRequests: true。
六、核心特性四：中断机制（Interrupts，人类介入流程）
Beta 特性：Interrupts 需要从
genkit/beta导入，而不是genkit：import { genkit } from 'genkit/beta';
中断（Interrupt）会暂停模型处理流程并将控制权交还给调用方，从而支持“人在回路”（human-in-the-loop）工作流。源码层面，中断通过抛出一个ToolInterruptError实现（js/ai/src/tool.ts），框架捕获该错误后将 toolRequest 放入响应并返回给调用方；defineInterrupt本质上创建的是一个元数据标记为restartable: false的工具（js/ai/src/tool.ts）。中断有两种模式：
6.1 基础中断（Basic Interrupts）
使用defineInterrupt创建一个始终暂停的工具，调用方通过.respond()提供响应：
const confirmAction = ai.defineInterrupt({ name: 'confirmAction', description: 'Confirm an action with the user before proceeding', inputSchema: z.object({ action: z.string(), reason: z.string() }), outputSchema: z.object({ approved: z.boolean() }), }); let response = await ai.generate({ model: googleAI.model('gemini-flash-latest'), prompt: 'Book a table for 2 at 7pm tonight', tools: [confirmAction], }); // The model triggered an interrupt — get user approval if (response.interrupts.length) { const interrupt = response.interrupts[0]; console.log(interrupt.toolRequest.input); // { action: '...', reason: '...' } // Resume with the user's response (bypasses tool execution) response = await ai.generate({ model: googleAI.model('gemini-flash-latest'), messages: response.messages, tools: [confirmAction], resume: { respond: confirmAction.respond(interrupt, { approved: true }), }, }); }流程拆解：首次generate触发中断后，response.interrupts携带中断详情；应用层（例如 UI）可据此向用户展示确认信息；用户批准后，通过resume.respond将confirmAction.respond(interrupt, { approved: true })作为人工回复注入新一轮生成，该回复会绕过工具执行直接作为 toolResponse 返回给模型。resume选项的完整语义见 js/ai/src/generate.ts：respond中的每条 toolResponse 都必须与最近模型消息中的 toolRequest 的name和ref匹配，工具提供的.respond辅助方法会自动完成 schema 校验。
6.2 可重启工具（Restartable Tools）
普通工具可以条件性调用interrupt()发起中断，并在获得批准后通过.restart()重新执行。resumed标志告知工具其已被批准：
const sendEmail = ai.defineTool( { name: 'sendEmail', description: 'Sends an email', inputSchema: z.object({ to: z.string(), body: z.string() }), outputSchema: z.object({ sent: z.boolean() }), }, async (input, { interrupt, resumed }) => { if (!resumed) { interrupt({ message: `Send email to ${input.to}?` }); } // Approved — proceed with sending return { sent: true }; } ); let response = await ai.generate({ model: googleAI.model('gemini-flash-latest'), prompt: 'Send a hello email to alice@example.com', tools: [sendEmail], }); if (response.interrupts.length) { const interrupt = response.interrupts[0]; // Restart re-executes the tool, this time with resumed=true response = await ai.generate({ model: googleAI.model('gemini-flash-latest'), messages: response.messages, tools: [sendEmail], resume: { restart: [sendEmail.restart(interrupt)] }, }); }重启语义在ResumeOptions.restart中定义（js/ai/src/generate.ts）：restart会以额外元数据再次运行该工具，元数据通过第二个参数的resumed选项传递，从而支持“先确认 LLM 的工具请求、再执行”的典型审批场景。两种模式的差异在于：defineInterrupt创建的工具永远暂停、必须人工回复；而可重启工具默认继续执行，仅在显式调用interrupt()时才暂停，且批准后会自动重新执行同一工具。
七、核心特性五：Prompt 管理（Dotprompt）
Genkit 支持将提示词作为代码进行管理，通过 frontmatter 内嵌 schema、模型配置，并使用 Handlebars 模板语法：
--- model: googleai/gemini-flash-latest input: schema: topic: string output: schema: title: string summary: string --- Write a blog post about {{topic}}.在代码中通过名称加载并执行：
const blogPrompt = ai.prompt('blog'); const { output } = await blogPrompt({ topic: 'AI safety' });ai.prompt('blog')默认从promptDir（GenkitOptions.promptDir，默认指向项目中的 prompts 目录）查找.prompt文件；Genkit.prompt还支持通过{ variant }参数选择变体（js/genkit/src/genkit.ts）。frontmatter 中声明的model、input.schema、output.schema会被自动解析并应用，模板中的{{topic}}由 Handlebars 渲染，blogPrompt({ topic: 'AI safety' })即为一次带类型校验的提示词调用。仓库中的真实示例可参考 samples/js-prompts 与 js/testapps/prompt-file。
八、核心特性六：Flows（可观测工作流与 API 服务）
Flow 用于构建强类型、完全可观测的工作流，既能作为 API 提供服务，也能从客户端访问：
import { genkit, z } from 'genkit'; import { googleAI } from '@genkit-ai/google-genai'; const ai = genkit({ plugins: [googleAI()], model: googleAI.model('gemini-flash-latest'), }); const RecipeSchema = z.object({ title: z.string(), ingredients: z.array(z.string()), instructions: z.array(z.string()), }); export const recipeFlow = ai.defineFlow( { name: 'recipeFlow', inputSchema: z.object({ ingredient: z.string() }), outputSchema: RecipeSchema, }, async (input) => { const { output } = await ai.generate({ prompt: `Create a recipe using ${input.ingredient}`, output: { schema: RecipeSchema }, }); if (!output) throw new Error('Failed to generate recipe'); return output; } );ai.defineFlow将 flow 注册进 registry 并追加到Genkit.flows列表（js/genkit/src/genkit.ts），每个 flow 拥有独立的输入/输出 schema 校验与分布式追踪能力。
8.1 作为 API 服务
使用 Express 插件把 flow 暴露为 HTTP 端点：
import { startFlowServer } from '@genkit-ai/express'; // npm i @genkit-ai/express startFlowServer({ flows: [recipeFlow] });startFlowServer定义于 js/plugins/express/src/index.ts，默认监听http://localhost:3400（Express 插件端口），将传入的 flows 数组逐一映射为对应路径的 HTTP 端点。除 Express 外，仓库还提供 Fastify（js/plugins/fastify）与 Hono 等适配方案，详见 js/testapps/hono。
8.2 客户端访问与流式消费
使用genkit/beta/client中的streamFlow从客户端消费 flow：
import { streamFlow } from 'genkit/beta/client'; const { stream } = streamFlow({ url: 'http://localhost:3500/recipeFlow', input: { ingredient: 'avocado' }, }); for await (const chunk of stream) { console.log(chunk); }streamFlow以流式方式拉取 flow 的输出，配合runFlow（一次性获取完整结果）使用，让浏览器/客户端能够实时展示 flow 执行进度。默认端口示例:3500为 Express flow server 的常见端口，实际端口以startFlowServer配置为准。
九、核心特性七：模型中间件（Middleware）
中间件可为 AI 请求统一附加通用能力，来源于genkit/model/middleware与@genkit-ai/middleware两个入口。以重试中间件为例：
import { retry } from 'genkit/model/middleware'; const { text } = await ai.generate({ model: googleAI.model('gemini-flash-latest'), prompt: 'Why is Genkit awesome?', use: [ retry({ maxRetries: 3, initialDelayMs: 1000, backoffFactor: 2, }), ], });retry中间件的完整默认值与行为可结合源码 js/ai/src/model/middleware.ts 理解：
maxRetries：最大重试次数，默认3；statuses：可重试的 HTTP 状态码集合，默认DEFAULT_RETRY_STATUSES（主要是 429/5xx 等瞬时错误）；initialDelayMs：首次重试前的延迟，默认1000毫秒；maxDelayMs：延迟上限，默认60000毫秒；backoffFactor：指数退避系数，默认2；noJitter：是否禁用抖动（jitter），默认false，启用时会在延迟中加入随机量以避免惊群效应；onError：每次重试前的回调钩子。
特别地，AbortError与ToolInterruptError被列入NEVER_RETRY_ERROR_NAMES（js/ai/src/model/middleware.ts），即中止请求与工具中断导致的错误永远不会重试。中间件通过GenerateOptions.use传入（js/ai/src/generate.ts），除retry外还包括fallback、augmentWithContext等，可在 js/ai/src/model/middleware.ts 中查阅完整清单。
十、更多资源与深入阅读
在仓库内可以继续深入以下内容：
- 完整 API 参考与教程：以本文对应的 js/index.typedoc.md 为索引，逐包阅读模块文档；
- 开发者工具（CLI 与 Developer UI）：CLI 源码位于 genkit-tools/cli，开发者工具服务器实现见 genkit-tools/common/src/server；
- 模型插件实现：Gemini 插件源码见 js/plugins/google-genai，OpenAI 兼容插件见 js/plugins/compat-oai，Ollama 本地模型插件见 js/plugins/ollama；
- Flow 服务部署：Express 插件 js/plugins/express、Fastify 插件 js/plugins/fastify、Firebase 集成 js/plugins/firebase；
- MCP 集成：Model Context Protocol 插件 js/plugins/mcp；
- 可运行示例：仓库内置大量可直接运行的测试应用，涵盖工具调用、中断、流式、多 Agent 等场景，见 js/testapps 与 samples 目录。
综上，从一次简单的ai.generate调用出发，Genkit JS 通过注册表驱动的组件体系，将模型、工具、Flow、Prompt、中间件统一纳入一个可观测、可调试、可扩展的框架之中：genkit主包负责核心编排，genkit/beta提供人类介入等前沿能力，各@genkit-ai/*插件则按需接入模型、向量库、框架适配器与可观测性服务。这正是 Genkit 在 Google 内部及外部生产环境中被广泛使用的原因所在。
【免费下载链接】genkitOpen-source framework for building agentic apps in JavaScript, Go, Dart, and Python, built and used in production by Google项目地址: https://gitcode.com/GitHub_Trending/ge/genkit
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
