Firebase Genkit 실전 튜토리얼: 내 앱에 AI 챗봇 1시간 만에 만들기 (코드 포함)

개발자님, AI 기능 추가 때문에 밤새우지 마세요

Firebase Genkit 실전 튜토리얼을 시작하며..

“우리 앱에도 요즘 유행하는 AI 챗봇 하나 붙여볼까?”

이런 생각이 들 때면, 곧바로 거대한 벽에 부딪히는 기분이 들곤 합니다. Python, TensorFlow, Vertex AI… 시작하기도 전에 배워야 할 것들이 산더미처럼 느껴지죠. Firebase를 능숙하게 다루는 우리 같은 앱 개발자에게는 배보다 배꼽이 더 큰 상황입니다.

만약 TypeScript로, Firebase Functions를 다루듯 AI 모델을 호출하고, 로컬에서 완벽하게 테스트한 뒤 단 한 줄의 명령어로 배포할 수 있는 방법이 있다면 어떨까요?

Google이 바로 그런 우리를 위해 Firebase Genkit을 출시했습니다. 이 글은 복잡한 이론은 걷어내고, 지금 당장 당신의 프로젝트에 AI 챗봇을 추가할 수 있도록 돕는 가장 실용적인 가이드입니다. 저를 따라오시면, 1시간 안에 여러분의 앱에서 Gemini AI가 답변하는 챗봇 프로토타입을 완성하게 될 겁니다.

그래서, Genkit이 정확히 뭔가요? (개발자 언어 번역)

Genkit은 한마디로 “AI 기능을 위한 백엔드 프레임워크”입니다. 우리가 Express.js나 Next.js로 웹 서버를 만들듯, Genkit은 AI 모델 연동, 프롬프트 관리, 데이터 처리 같은 AI 관련 로직을 체계적으로 구성하고 배포할 수 있게 도와줍니다.

그럼 기존 Firebase AI 확장 프로그램과는 뭐가 다른가요?

• Firebase AI 확장 프로그램: 이미 완성된 ‘가전제품’과 같습니다. “이미지 리사이징”, “챗봇” 등 정해진 기능을 클릭 몇 번으로 설치해서 바로 쓸 수 있습니다. 아주 편리하지만, 내 입맛에 맞게 내부 로직을 수정하기는 어렵습니다.
• Firebase Genkit: 잘 설계된 ‘레고 블록 세트’와 같습니다. Gemini 모델, 벡터 데이터베이스, 외부 API 등 다양한 블록(플러그인)을 제공하고, 우리는 이 블록들을 TypeScript 코드로 자유롭게 조립해서 우리 앱만을 위한 맞춤형 AI 기능을 만들 수 있습니다. 개발 유연성이 비교할 수 없이 높죠.

결론적으로, 정해진 기능만 필요하다면 AI 확장 프로그램이 빠르고, 우리 서비스에 특화된 AI 로직을 만들고 싶다면 Genkit이 정답입니다.

Genkit 실전 튜토리얼: 나만의 메뉴 추천 챗봇 만들기

이제 A부터 Z까지, 간단한 Q&A 챗봇을 직접 만들어 보겠습니다. “오늘 뭐 먹지?”라는 질문에 재미있는 메뉴를 추천해 주는 챗봇입니다.

1단계: 개발 환경 설정 (5분)

먼저 Genkit을 사용할 수 있도록 컴퓨터에 도구를 설치하고 프로젝트를 초기화합니다.

1. Node.js 설치: 버전 20 이상이 필요합니다.
2. Genkit CLI 설치: 터미널에 다음 명령어를 입력하세요.
   Bash

   npm i -g genkit
   

3. Firebase 프로젝트 준비: 기존 Firebase 프로젝트를 사용하거나 새로 하나 만드세요. Blaze 요금제(종량제) 활성화는 필수입니다.
4. 프로젝트 초기화: 원하는 폴더에서 다음 명령어를 실행합니다.
   Bash

   genkit init
   

   명령어를 실행하면 몇 가지 질문이 나옵니다.

   • Deployment platform: Firebase Cloud Functions 선택
   • Model provider: Google AI (Gemini API) 선택
   • Project template: Firebase 선택
   • 이후 Firebase 프로젝트 연결 질문에는 firebase login, firebase projects:list 등으로 프로젝트 ID를 확인하여 답변합니다.

모든 과정이 끝나면 index.ts 파일을 포함한 기본 구조가 생성됩니다.

2단계: “Hello Genkit!” – 첫 Flow 실행하기 (5분)

AI를 연결하기 전에, Genkit이 잘 작동하는지 가장 간단한 코드로 확인해 보겠습니다. index.ts 파일의 모든 내용을 지우고 아래 코드를 붙여넣으세요.

// index.ts

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

// Genkit 설정을 초기화합니다. Firebase 플러그인을 사용하도록 설정합니다.
configureGenkit({
  plugins: [firebase()], // Firebase Functions와 통합을 위한 플러그인
  logSinks: ['firebase'], // 로그를 Firebase에 저장
  enableTracingAndMetrics: true, // 성능 추적 및 메트릭 활성화
});

import { defineFlow } from '@genkit-ai/flow';
import * as z from 'zod'; // 데이터 형식 검증을 위한 라이브러리

// 'helloGenkit'이라는 이름의 Flow(AI 작업 단위)를 정의합니다.
export const helloGenkit = defineFlow(
  {
    name: 'helloGenkit', // Flow의 고유 이름
    inputSchema: z.string(), // 입력 데이터는 문자열(string) 타입
    outputSchema: z.string(), // 출력 데이터도 문자열(string) 타입
  },
  async (name) => {
    // 입력받은 이름에 환영 메시지를 붙여 반환합니다.
    return `Hello, ${name}! Welcome to Genkit.`;
  }
);

이제 터미널에서 Genkit의 핵심 기능인 개발자 UI를 실행해 봅시다.

genkit start

이 명령어를 실행하면 localhost:4000 주소로 개발 서버가 열립니다. 브라우저에서 해당 주소로 접속해 보세요.

왼쪽 메뉴에서 helloGenkit을 클릭하고, 입력 필드에 “김프로” 같은 이름을 넣은 뒤 ‘Run’ 버튼을 눌러보세요. 오른쪽에 “Hello, 김프로! Welcome to Genkit.”이라는 결과가 나오면 성공입니다! 이 UI를 통해 우리는 코드를 배포하기 전에 모든 입력과 출력을 시각적으로 확인하며 완벽하게 디버깅할 수 있습니다.

3단계: 똑똑한 두뇌 이식하기 – Gemini 모델 연동 (15분)

이제 진짜 AI, Gemini 모델을 연결할 차례입니다.

1. Google AI API Key 발급: Google AI Studio에 접속하여 API 키를 발급받으세요.
2. API Key 설정: 프로젝트 루트 폴더에 .env 파일을 만들고 아래와 같이 키를 추가합니다. .env 파일은 Git에 포함되지 않도록 .gitignore에 추가하는 것을 잊지 마세요.

   GOOGLE_API_KEY="여기에_발급받은_API_키를_붙여넣으세요"
   

3. 메뉴 추천 Flow 작성: index.ts 파일의 내용을 아래 코드로 교체합니다.

// index.ts

import { configureGenkit } from '@genkit-ai/core';
import { firebase } from '@genkit-ai/firebase';
import { googleAI } from '@genkit-ai/googleai'; // Google AI(Gemini) 플러그인 추가

// .env 파일의 환경 변수를 로드합니다.
import *e from 'dotenv/config'; 

configureGenkit({
  plugins: [
    firebase(),
    googleAI({ apiKey: process.env.GOOGLE_API_KEY }), // Gemini API 키를 사용하여 플러그인 설정
  ],
  logSinks: ['firebase'],
  enableTracingAndMetrics: true,
});

import { defineFlow } from '@genkit-ai/flow';
import { generate } from '@genkit-ai/ai';
import { geminiPro } from '@genkit-ai/googleai'; // 사용할 모델(gemini-pro)을 가져옵니다.
import * as z from 'zod';

// 'menuRecommender' Flow를 정의합니다.
export const menuRecommender = defineFlow(
  {
    name: 'menuRecommender',
    inputSchema: z.object({ mood: z.string() }), // 입력은 'mood'라는 키를 가진 객체
    outputSchema: z.string(),
  },
  async ({ mood }) => {
    // AI에게 생성(generate)을 요청합니다.
    const response = await generate({
      model: geminiPro, // 사용할 AI 모델 지정
      prompt: `
        당신은 변덕스러운 직장인을 위한 메뉴 추천 전문가입니다.
        사용자의 현재 기분(${mood})을 고려해서, 아주 재치있고 창의적인 메뉴 1개와 그 메뉴를 추천하는 이유를 2문장 이내로 설명해주세요.
        답변은 "오늘의 추천 메뉴: [메뉴 이름]\n이유: [추천 이유]" 형식으로만 작성해주세요.
      `,
      config: {
        // 창의적인 답변을 위해 temperature 값을 약간 높게 설정
        temperature: 0.8,
      },
    });

    return response.text(); // 생성된 텍스트만 반환
  }
);

다시 genkit start를 실행하고 개발자 UI(localhost:4000)를 확인해 보세요. 새로 생긴 menuRecommender Flow를 테스트할 수 있습니다. {"mood": "조금 우울해요"} 와 같이 JSON 형식으로 입력하면 Gemini가 재치있는 답변을 생성해 줄 겁니다.

4단계: 내 앱과 연결하기 – 클라이언트 코드 작성 (10분)

이제 이 Flow를 실제 웹이나 앱에서 호출할 수 있도록 Firebase에 배포하고 클라이언트 코드를 작성해 봅시다.

1. Firebase에 배포: 터미널을 열고 다음 명령어를 실행하면 끝입니다.
   Bash

   enkit deploy
   

   이 명령어는 Genkit이 알아서 menuRecommender Flow를 Firebase Cloud Function으로 만들어 배포해 줍니다.

2. 클라이언트(웹)에서 호출: 웹 앱에서 이 함수를 호출하는 예제 코드입니다. (Firebase SDK가 이미 설정되어 있다고 가정합니다.)

// web-app.js

import { getFunctions, httpsCallable } from "firebase/functions";

const functions = getFunctions();
// 배포된 Genkit Flow의 이름(menuRecommender)으로 호출 가능한 함수를 참조합니다.
const recommendMenu = httpsCallable(functions, 'menuRecommender');

async function getMenuRecommendation(userMood) {
  try {
    // Flow를 호출할 때는 inputSchema에 정의한 대로 객체 형태로 데이터를 전달합니다.
    const result = await recommendMenu({ mood: userMood });
    
    // result.data에 Flow의 반환값이 들어있습니다.
    console.log("AI의 추천:", result.data); 
    // 이 데이터를 화면에 표시합니다.
    document.getElementById('result-display').innerText = result.data;

  } catch (error) {
    console.error("메뉴 추천 중 오류 발생:", error);
    // 에러 처리 로직
  }
}

// 예: 버튼 클릭 시 함수 호출
document.getElementById('recommend-button').addEventListener('click', () => {
  const mood = document.getElementById('mood-input').value;
  getMenuRecommendation(mood);
});

이제 당신의 앱은 AI 챗봇의 두뇌(Genkit Flow)와 대화할 수 있게 되었습니다!

레벨업: RAG로 ‘우리 회사 전문가’ 챗봇 만들기

지금 만든 챗봇은 일반적인 지식으로만 답변합니다. 만약 “우리 회사 제품 A의 사용법을 알려줘” 와 같은 질문에 답하게 하려면 어떻게 해야 할까요? 바로 이럴 때 RAG (검색 증강 생성, Retrieval-Augmented Generation) 기술이 사용됩니다.

Genkit은 RAG 앱 만들기를 매우 간단하게 만들어 줍니다.

RAG의 원리 (쉽게 이해하기):

1. 자료 준비 (Indexing): 우리 회사 제품 매뉴얼, FAQ 문서들을 미리 잘게 쪼개서 AI가 이해하기 쉬운 형태(벡터)로 변환한 뒤 ‘서랍장(벡터 DB)’에 넣어둡니다. (index 함수 사용)
2. 질문 연관 자료 찾기 (Retrieving): 사용자가 질문하면, 질문과 가장 관련 있는 자료를 서랍장에서 꺼냅니다. (retrieve 함수 사용)
3. 자료 기반 답변 생성 (Generating): AI에게 “이 자료들을 참고해서 답변해 줘” 라고 질문과 함께 꺼내 온 자료를 넘겨줍니다.

마치 AI에게 ‘오픈북 테스트’를 보게 하는 것과 같습니다. Genkit은 이런 과정을 위한 embed, index, retrieve 와 같은 도구들을 모두 제공하여, 복잡한 RAG 파이프라인을 몇 줄의 코드로 구현할 수 있게 해줍니다.

결론: AI, 더 이상 남의 기술이 아닙니다

오늘 우리는 Firebase Genkit을 사용해 단 1시간도 안 되어 AI 챗봇의 핵심 로직을 만들고, 테스트하고, 실제 앱과 연동하는 전 과정을 경험했습니다. Genkit은 복잡한 AI 인프라 대신, 우리가 가장 잘하는 TypeScript 코드에 집중하게 해줍니다.

이제 AI 기능 추가는 더 이상 막막한 연구 과제가 아닌, 익숙한 API를 하나 더 연동하는 개발의 일부가 되었습니다. 오늘 만든 작은 챗봇을 시작으로, 여러분의 서비스에 날개를 달아줄 무한한 AI 기능을 상상하고 구현해 보세요.

FAQ (자주 묻는 질문)

Q1: Google AI API Key는 어디서 발급받고 어떻게 설정해야 하나요?

A: Google AI Studio에서 ‘Create API key in new project’ 버튼을 눌러 발급받을 수 있습니다. 발급받은 키는 프로젝트 루트에 .env 파일을 생성하고 GOOGLE_API_KEY="YOUR_API_KEY" 형식으로 저장하면 Genkit이 자동으로 인식합니다.

Q2: 로컬에서는 잘 되는데 Firebase에 배포 후 에러가 발생합니다.

A: 가장 흔한 원인은 권한(IAM) 문제입니다. Firebase 프로젝트의 Cloud Functions 관련 서비스 계정(service-@gcp-project-id.iam.gserviceaccount.com)에 ‘Cloud AI Companion User’와 ‘Vertex AI User’ 역할이 부여되었는지 Google Cloud Console의 IAM 페이지에서 확인해 보세요. 또한, 함수가 배포된 리전과 Google AI 서비스 사용 가능 리전이 맞는지 확인해야 합니다.

Q3: Genkit 사용 비용은 어떻게 되나요?

A: Genkit 프레임워크 자체는 무료입니다. 비용은 크게 두 가지에서 발생합니다. 첫째, 호출하는 AI 모델(예: Gemini API)의 사용량에 따른 비용. 둘째, Genkit Flow가 배포된 Firebase Cloud Functions의 호출 횟수 및 실행 시간에 따른 비용입니다. 자세한 내용은 각 서비스의 요금 정책을 참고하세요.