從 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({...});

  • 個別設定記錄層級 ```js 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 變更

Genkit 0.9 中，指令列介面 (CLI) 經過重大更新。啟動 Genkit 的指令已變更，CLI 也已分離為獨立套件，因此您現在必須分別安裝這兩者。

如要安裝 CLI，請按照下列步驟操作：

npm i -g genkit-cli

我們對 genkit start 指令做出了以下變更：

一起啟動 Genkit 應用程式程式碼和開發人員 UI：

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

僅啟動開發人員 UI：

genkit start

先前，genkit start 指令會一併啟動開發人員使用者介面和應用程式程式碼。如果您有任何依賴此指令的 CI/CD 管道，可能需要更新管道。

開發人員 UI 會直接與流程伺服器互動，找出已註冊的流程，並讓您直接使用範例輸入內容叫用這些流程。

2. 簡化套件和匯入作業

先前，Genkit 程式庫會分成多個模組，您必須個別安裝及匯入這些模組。這些模組現已整合為單一匯入項目。此外，Genkit 現已重新匯出 Zod 模組。

舊版：

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

先前，初始化 Genkit 是透過呼叫 configureGenkit 函式在全球範圍內完成。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. 以 getter 屬性取代 GenerateResponse 類別方法

先前，您會使用類別方法 (例如 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');