모든 Node.js 플랫폼에 흐름 배포

Firebase Genkit에는 Firebase용 Cloud Functions 및 Google Cloud Run에 흐름을 배포하는 데 도움이 되는 통합이 내장되어 있지만 클라우드 서비스이든 셀프 호스팅이든 Express.js 앱을 제공할 수 있는 모든 플랫폼에 흐름을 배포할 수도 있습니다.

예를 들어 이 페이지에서는 기본 샘플 흐름을 배포하는 프로세스를 안내합니다.

시작하기 전에

  • Node.js 20 이상: 환경에서 Node.js 버전 20 이상을 사용하고 있는지 확인합니다 (node --version).
  • Genkit의 플로우 개념을 숙지해야 합니다.

1. 프로젝트 설정

  1. 프로젝트 디렉터리 만들기:

    export GENKIT_PROJECT_HOME=~/tmp/genkit-express-project
mkdir -p $GENKIT_PROJECT_HOME
cd $GENKIT_PROJECT_HOME

  2. Node.js 프로젝트 초기화:

    npm init -y

  3. Genkit 및 필요한 종속 항목 설치:

    npm install --save genkit @genkit-ai/googleai
npm install -D genkit-cli typescript tsx

2. Genkit 앱 구성

  1. 샘플 흐름 및 서버 설정:

src/index.ts에서 샘플 흐름을 정의하고 흐름 서버를 구성합니다.

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

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

  const helloFlow = ai.defineFlow(
    {
      name: 'helloFlow',
      inputSchema: z.object({ name: z.string() }),
      outputSchema: z.string(),
    },
    async (input) => {
      const { text } = ai.generate('Say hello to ${input.name}');
      return text;
    }
  );

  startFlowServer({
    flows: [menuSuggestionFlow],
  });

지정할 수 있는 startFlowServer의 선택적 매개변수도 있습니다.

  • port: 리슨할 네트워크 포트입니다. 지정하지 않으면 서버가 PORT 환경 변수에 정의된 포트에서 리슨하고 PORT가 설정되지 않으면 기본값 3400으로 설정됩니다.
  • cors: 흐름 서버의 CORS 정책입니다. 웹 애플리케이션에서 이러한 엔드포인트에 액세스하는 경우 이를 지정해야 할 수 있습니다.
  • pathPrefix: 흐름 엔드포인트 앞에 추가할 선택적 경로 접두사입니다.
  • jsonParserOptions: Express의 JSON 본문 파서에 전달할 옵션입니다.
  1. 모델 제공업체 사용자 인증 정보 설정:

모델 제공업체에 필요한 환경 변수를 구성합니다. 이 가이드에서는 Google AI Studio의 Gemini API를 예로 들겠습니다.

Google AI Studio에서 API 키 가져오기

API 키를 만든 후 다음 명령어를 사용하여 GOOGLE_GENAI_API_KEY 환경 변수를 키로 설정합니다.

  export GOOGLE_GENAI_API_KEY=<your API key>

배포 제공업체에 따라 환경에서 API 키를 보호하는 방법이 다릅니다. 보안을 위해 API 키가 공개적으로 노출되지 않도록 합니다.

3. 배포를 위한 Node.js 프로젝트 준비

package.json에 시작 및 빌드 스크립트 추가

Node.js 프로젝트를 배포하려면 package.json에서 start 및 build 스크립트를 정의합니다. TypeScript 프로젝트의 경우 이러한 스크립트는 다음과 같습니다.

"scripts": {
  "start": "node --watch lib/index.js",
  "build": "tsc"
},

로컬에서 빌드 및 테스트

빌드 명령어를 실행한 다음 서버를 시작하고 로컬에서 테스트하여 예상대로 작동하는지 확인합니다.

npm run build
npm start

다른 터미널 창에서 엔드포인트를 테스트합니다.

curl -X POST "http://127.0.0.1:3400/menuSuggestionFlow" \
  -H "Content-Type: application/json" \
  -d '{"data": "banana"}'

선택사항: 개발자 UI 시작

개발 중에 개발자 UI를 사용하여 흐름을 대화형으로 테스트할 수 있습니다.

npx genkit start -- npm run start

http://localhost:4000/flows로 이동하여 UI에서 흐름을 테스트합니다.

4. 프로젝트 배포

프로젝트가 로컬에서 구성되고 테스트되면 Node.js 호환 플랫폼에 배포할 준비가 됩니다. 배포 단계는 제공업체에 따라 다르지만 일반적으로 다음 설정을 구성합니다.

설정 값
런타임 Node.js 20 이상
빌드 명령어 npm run build
시작 명령어 npm start
환경 변수 GOOGLE_GENAI_API_KEY=<your-api-key> 및 기타 필요한 보안 비밀 설정

start 명령어(npm start)는 컴파일된 진입점(일반적으로 lib/index.js)을 가리켜야 합니다. 배포 플랫폼에 필요한 모든 환경 변수를 추가해야 합니다.

배포한 후 제공된 서비스 URL을 사용하여 흐름을 HTTPS 엔드포인트로 호출할 수 있습니다.