从 0.5 迁移

Genkit 0.9 引入了一些破坏性更改，同时增强了一些功能，以提升整体功能。如果您一直在使用 Genkit 0.5 开发应用，则在升级到最新版本时，需要更新应用代码。本指南概述了最重大的变更，并提供了顺利迁移现有应用的步骤。

快速入门指南

以下步骤可帮助您快速从 Genkit 0.5 迁移到 Genkit 0.9。如需详细了解这些变更，请参阅下方的详细更新日志。

1. 安装新版 CLI

• 卸载旧版 CLI

  npm uninstall -g genkit && npm uninstall genkit
  

• 安装新版 CLI

  npm i -D genkit-cli
  

2. 更新依赖项

• 移除各个 Genkit 核心软件包

  npm uninstall @genkit-ai/ai @genkit-ai/core @genkit-ai/dotprompt @genkit-ai/flow
  

• 安装新的合并 genkit 软件包

  npm i --save genkit
  

• 升级所有插件版本（示例见下文）

  npm upgrade @genkit-ai/firebase
  

3. 更改导入内容

• 移除了各个 Genkit 核心软件包的导入

  import { … } from '@genkit-ai/ai';
  import { … } from '@genkit-ai/core';
  import { … } from '@genkit-ai/flow';
  

• 移除 zod 导入

  import * as z from 'zod';
  

• 从 genkit 导入 genkit 和 zod

  import { z, genkit } from 'genkit';
  

4. 更新代码

移除 configureGenkit 块

现在，Genkit 的配置是按实例进行的。遥测和日志记录是全局配置的，与 Genkit 实例分开。

• 将 configureGenkit 替换为 ai = genkit({...}) 块。仅保留插件配置。

  import { genkit } from 'genkit';
  
  const ai = genkit({ plugins: [...]});
  

• 使用 enableFirebaseTelemetry 或 enableGoogleCloudTelemetry 配置遥测

  对于 Firebase：

  import { enableFirebaseTelemetry } from '@genkit-ai/firebase';
  enableFirebaseTelemetry({...});
  

  对于 Google Cloud：

  import { enableGoogleCloudTelemetry } from '@genkit-ai/google-cloud';
  enableGoogleCloudTelemetry({...});
  

• 独立设置日志记录级别

  import { logger } from 'genkit/logging';
  
  logger.setLogLevel('debug');
  

如需详细了解如何配置遥测和日志记录，请参阅监控和日志记录文档。

如需详细了解如何配置 Genkit 实例，请参阅开始使用文档。

将 Genkit 操作迁移到从 genkit 实例调用

操作（流程、工具、检索工具、索引编制工具等）是按实例定义的。请参阅更新日志，了解您需要更改的所有功能，但下面列出了一些常见的示例。

import { genkit } from 'genkit';
import { onFlow } from '@genkit-ai/firebase/functions';

const ai = genkit({ plugins: [...]});

// Flows and tools are defined on the specific genkit instance
// and are directly callable.
const sampleFlow = ai.defineFlow(...);
const sampleTool = ai.defineTool(...);

async function callMyFlow() {
  // Previously, text output could accessed via .text()
  // Now it is either .output() or .text
  return await sampleFlow().output();
}

// onFlow now takes the Genkit instance as first argument
// This registers the flow as a callable firebase function
onFlow(ai, ...);
const flows = [ sampleFlow, ... ];
// Start the flow server to make the registered flows callable over HTTP
ai.startFlowServer({flows});

5. 运行应用

# run the DevUI and your js code
genkit start -- <command to run node>
# run a defined flow
genkit flow:run <flowName>

变更日志

1. CLI 变更

命令行界面 (CLI) 在 Genkit 0.9 中进行了重大更新。启动 Genkit 的命令已更改，CLI 已分离为自己的独立软件包，您现在需要单独安装该软件包。

如需安装 CLI，请执行以下操作：

npm i -g genkit-cli

对 genkit start 命令进行了一些更改：

一起启动 Genkit 应用代码 + 开发者界面：

genkit start -- [start command]
genkit start -- tsx src/index.ts
genkit start -- go run main.go

还支持观看模式：

genkit start -- tsx --watch src/index.ts

仅在 Genkit 开发模式下启动应用代码：

genkit start --noui -- <start command>
genkit start --noui -- tsx src/index.ts

仅启动开发者界面：

genkit start

以前，genkit start 命令会同时启动开发者界面和应用代码。如果您有任何依赖于此命令的 CI/CD 流水线，则可能需要更新该流水线。

开发者界面将直接与流服务器交互，以确定已注册哪些流，并允许您使用示例输入直接调用这些流。

2. 简化了软件包和导入

以前，Genkit 库分为多个模块，您需要单独安装和导入这些模块。这些模块现已合并为单个导入项。此外，Zod 模块现在由 Genkit 重新导出。

旧版：

npm i @genkit-ai/core @genkit-ai/ai @genkit-ai/flow @genkit-ai/dotprompt

新功能：

npm i genkit

旧版：

import { … } from '@genkit-ai/ai';
import { … } from '@genkit-ai/core';
import { … } from '@genkit-ai/flow';
import * as z from 'zod';

新功能：

import { genkit, z } from 'genkit';

Genkit 插件仍需单独安装和导入。

3. 配置 Genkit

以前，通过调用 configureGenkit 函数，系统会全局完成一次 Genkit 初始化。Genkit 资源（流程、工具、提示等）都将自动与此全局配置关联。

Genkit 0.9 引入了 Genkit 实例，每个实例封装一个配置。请参见以下示例：

旧版：

import { configureGenkit } from '@genkit-ai/core';

configureGenkit({
  telemetry: {
    instrumentation: ...,
    logger: ...
  }
});

新功能：

import { genkit } from 'genkit';
import { logger } from 'genkit/logging';
import { enableFirebaseTelemetry } from '@genkit-ai/firebase';

logger.setLogLevel('debug');
enableFirebaseTelemetry({...});

const ai = genkit({ ... });

我们来详细了解一下：

• configureGenkit() 已替换为 genkit()，它会返回已配置的 Genkit 实例，而不是全局设置配置。
• Genkit 初始化函数现已位于 genkit 软件包中。
• 日志记录和遥测功能仍使用各自的显式方法进行全局配置。这些配置会统一应用于所有 Genkit 实例。

4. 显式定义流程并启动流程服务器

现在，您已经配置了 Genkit 实例，接下来需要定义数据流。现在，所有面向开发者的核心 API 方法（例如 defineFlow、defineTool 和 onFlow）都通过此实例调用。

这与之前的流程和工具在全球注册的方式不同。

旧版：

import { defineFlow, defineTool, onFlow } from '@genkit-ai/core';

defineFlow(...);
defineTool(...);

onFlow(...);

新功能：

// Define tools and flows
const sampleFlow = ai.defineFlow(...);
const sampleTool = ai.defineTool(...);

// onFlow now takes the Genkit instance as first argument
// This registers the flow as a callable firebase function
onFlow(ai, ...);  

const flows = [ sampleFlow, ... ];
// Start the flow server to make the registered flows callable over HTTP
ai.startFlowServer({flows});

目前，您要提供的所有流程都需要在上述 flows 数组中明确注册。

5. 必须静态定义工具和提示

在较低版本的 Genkit 中，您可以直接在流程内动态定义工具和提示。

在 Genkit 0.9 中，不再允许这种行为。相反，您需要在流程执行之外（即静态）定义所有操作和流程。

这项更改强制执行更严格的操作定义与执行分离。

如果您的任何代码是动态定义的，则需要进行重构。否则，在运行时执行流程时，系统会抛出错误。

❌ 不应：

const flow = defineFlow({...}, async (input) => {
  const tool = defineTool({...});
  await tool(...);
});

✅ 正确做法：

const tool = ai.defineTool({...});

const flow = ai.defineFlow({...}, async (input) => {
  await tool(...);
});

6. 适用于流式传输流的新 API

在 Genkit 0.9 中，我们简化了定义和调用流式传输流的语法。

首先，defineFlow 和 defineStreamingFlow 已分离。如果您有要流式传输的流程，则必须更新代码，以便通过 defineStreamingFlow 定义它。

其次，现在，流和响应都是直接从流程返回的值，而不是调用单独的 stream() 和 response() 函数。此更改简化了数据流式传输。

旧版：

import { defineFlow, streamFlow } from '@genkit-ai/flow';

const myStreamingFlow = defineFlow(...);
const { stream, output } = await streamFlow(myStreamingFlow, ...);

for await (const chunk of stream()) {
  console.log(chunk);
}

console.log(await output());

新功能：

const myStreamingFlow = ai.defineStreamingFlow(...);
const { stream, response } = await myStreamingFlow(...);

for await (const chunk of stream) {
  console.log(chunk);
}

console.log(await response);

7. 将 GenerateResponse 类方法替换为 getter 属性

以前，您使用类方法（例如 output() 或 text()）访问响应的结构化输出或文本。

在 Genkit 0.9 中，这些方法已被 getter 属性取代。这样可以简化对回复的处理。

旧版：

const response = await generate({ prompt: 'hi' });
console.log(response.text());

新功能：

const response = await ai.generate('hi');
console.log(response.text);

output 也是如此：

旧版：

console.log(response.output());

新功能：

console.log(response.output);

8. 取消了候选集生成

Genkit 0.9 移除了 candidates 属性，从而简化了响应处理。以前，响应可以包含多个候选人，您需要明确处理这些候选人。现在，只有第一个候选项会直接返回在扁平响应中。

任何直接访问候选对象的代码都将失效。

旧版：

const response = await generate({
 messages: [ { role: 'user', content: ...} ]
});
console.log(response.candidates); // previously you could access candidates directly

新功能：

const response = await ai.generate({
 messages: [ { role: 'user', content: ...} ]
});
console.log(response.message); // single candidate is returned directly in a flat response

9. Generate API - 增强了多轮对话功能

对于多轮对话，旧的 toHistory() 方法已被 messages 取代，进一步简化了对话记录的处理方式。

旧版：

const history = response.toHistory();

新功能：

const response = await ai.generate({
 messages: [ { role: 'user', content: ...} ]
});
const history = response.messages;

10. 简化版 Chat API

在 Genkit 0.9 中，Chat API 经过了重新设计，可让您更轻松地管理会话和进行互动。您可以通过以下方式将其用于同步和流式聊天体验：

import { genkit } from 'genkit';
import { gemini15Flash, googleAI } from '@genkit-ai/googleai';

const ai = genkit({
 plugins: [googleAI()],
 model: gemini15Flash,
});

const session = ai.createSession({ store: firestoreSessionStore() });
const chat = await session.chat({ system: 'talk like a pirate' });

let response = await chat.send('hi, my name is Pavel');
console.log(response.text()); // "hi Pavel, I'm llm"

// continue the conversation
response = await chat.send("what's my name");
console.log(response.text()); // "Pavel"

// can stream
const { response, stream } = await chat.sendStream('bye');
for await (const chunk of stream) {
 console.log(chunk.text());
}
console.log((await response).text());

// can load session from the store
const prevSession = await ai.loadSession(session.id, { store });
const prevChat = await prevSession.chat();
await prevChat.send('bye');