Genkit实战：15分钟搭建带RAG的AI应用

上周接手内部知识库的AI问答助手需求时，调研了多种集成方案，发现通用链路普遍冗长，工具调用逻辑也容易与业务代码深度耦合。尝试Google开源的Genkit框架后，原本预计三天的开发周期，两小时就跑通了核心原型。本文将完整记录从零到一搭建支持「文档检索+工具调用」AI应用的全过程。掌握这套工作流后，你将具备独立构建生产级AI应用的能力，直接聚焦业务逻辑而非底层胶水代码。

前置准备

开始前核对清单：Node.js版本需≥18.0，以支撑现代异步语法与模块规范；本地安装npm/yarn/pnpm任一包管理器；准备OpenAI或Google Cloud API密钥；具备基础TypeScript语法认知，Genkit生态以此为主力开发语言。

环境搭建三步走

1. 安装核心依赖

Genkit采用插件化架构，基础运行时仅保留调度引擎，具体模型或云端能力按需加载。在项目目录执行：

mkdir genkit-demo && cd genkit-demo
npm init -y
npm install genkit @genkit-ai/openai @genkit-ai/flow

这种拆分设计有效避免安装包体积膨胀。若业务仅依赖OpenAI模型，无需引入Google Vertex AI等其他SDK，保持依赖树干净且构建速度更快。

2. 生成配置文件

项目根目录新建 genkit.config.ts，写入初始化逻辑：

import { genkit } from 'genkit';
import { openai } from '@genkit-ai/openai';

export const ai = genkit({
  plugins: [
    openai({ apiKey: process.env.OPENAI_API_KEY })
  ]
});

配置对象充当应用中枢。插件数组注入后，框架自动注册对应能力池。后续调用 ai.model('gpt-4') 时，无需重复实例化客户端或处理鉴权细节，底层连接由插件统一维护。

3. 启动开发服务器

终端执行 npx genkit start，服务默认监听 http://localhost:4000。内置Playground提供交互式测试面板，API文档随代码变更实时更新。热重载机制已深度集成，修改配置文件或业务逻辑后保存即可生效，彻底告别手动重启。

实战：智能技术支持Agent

目标实现具备内部文档检索与外部诊断工具调用能力的智能体。开发拆分为模型绑定、工具注册、流式管道串联三个模块。

核心代码实现

import { z } from 'zod';
import { ai } from './genkit.config';

// 注册诊断工具
ai.defineTool(
  {
    name: 'runDiagnostics',
    description: '执行系统健康检查',
    inputSchema: z.object({ service: z.string() }),
  },
  async ({ service }) => {
    // 模拟真实诊断逻辑
    return { status: 'healthy', uptime: '72h' };
  }
);

// 构建RAG处理流
export const supportFlow = ai.defineFlow(
  {
    name: 'supportFlow',
    inputSchema: z.string(),
    outputSchema: z.string(),
  },
  async (query) => {
    const docs = await ai.retrieve({ 
      query, 
      retriever: 'internalDocs' // 需提前配置索引
    });
    
    const result = await ai.generate({
      model: 'gpt-4-turbo',
      prompt: `基于文档：${docs.content}\n回答：${query}`,
      tools: ['runDiagnostics'] // 关联已注册工具
    });
    
    return result.text;
  }
);

关键设计解析

类型安全方面，Zod 在编译期与运行期双重校验输入输出，避免动态语言常见的静默失败。流式编排优势在于将复杂业务拆解为可测试、可复用的管道节点，每个节点支持独立压测与版本回滚。上下文注入策略采用模板字符串混合检索结果，相比单一 System Prompt，能更精准控制信息边界，降低模型幻觉概率。

常见问题排查

Playground 提示「Plugin not loaded」
优先核对配置文件路径是否被主入口正确引用，同时确认各插件包版本与 Genkit 主版本兼容（当前建议锁定 ≥0.5.0）。

工具调用未触发
检查两点：所选模型必须原生支持 Function Calling 协议（如 gpt-3.5-turbo-0613 及以上版本）；tools 数组传入的字符串必须与 defineTool 声明的 name 字段完全一致，大小写敏感。

本地模拟 API 限流或网络波动
可在 Flow 外层包裹重试策略。结合指数退避算法与 Genkit 内置的异常处理机制，能显著提升服务在高并发或网络抖动场景下的可用性。

下一步建议

跑通基础链路后，可沿三个方向深化：替换底层模型提供商，安装对应云插件即可无缝切换至 Vertex AI 或其他兼容端点；接入多模态能力，通过扩展插件解析图像或音频输入；面向生产部署，执行 genkit deploy 自动生成容器化镜像并推送至目标环境。

完整示例代码已同步至 GitHub 仓库 genkit-ai/genkit，欢迎 Star 与 Issue 交流。