Vertex AI 플러그인은 다음과 같은 여러 AI 서비스에 대한 인터페이스를 제공합니다.
- Google 생성형 AI 모델:
- Gemini 텍스트 생성
- Imagen2 및 Imagen3 이미지 생성
- 텍스트 임베딩 생성
- Vertex AI Rapid Evaluation API를 통한 평가 측정항목의 하위 집합입니다.
- 벡터 검색
설치
npm i --save @genkit-ai/vertexai이 플러그인을 사용하는 흐름을 로컬에서 실행하려면 Google Cloud CLI 도구도 설치해야 합니다.
구성
이 플러그인을 사용하려면 Genkit를 초기화할 때 지정합니다.
import { genkit } from 'genkit';
import { vertexAI } from '@genkit-ai/vertexai';
const ai = genkit({
plugins: [
vertexAI({ location: 'us-central1' }),
],
});
플러그인을 사용하려면 Google Cloud 프로젝트 ID, Vertex API 요청을 수행할 리전, Google Cloud 프로젝트 사용자 인증 정보를 지정해야 합니다.
vertexAI()구성에서projectId를 설정하거나GCLOUD_PROJECT환경 변수를 설정하여 Google Cloud 프로젝트 ID를 지정할 수 있습니다. Google Cloud 환경 (Cloud Functions, Cloud Run 등)에서 흐름을 실행하는 경우GCLOUD_PROJECT는 자동으로 환경의 프로젝트 ID로 설정됩니다.vertexAI()구성에서location를 설정하거나GCLOUD_LOCATION환경 변수를 설정하여 API 위치를 지정할 수 있습니다.API 사용자 인증 정보를 제공하려면 Google Cloud 애플리케이션 기본 사용자 인증 정보를 설정해야 합니다.
사용자 인증 정보를 지정하려면 다음 단계를 따르세요.
- Google Cloud 환경 (Cloud Functions, Cloud Run 등)에서 흐름을 실행하는 경우 이는 자동으로 설정됩니다.
로컬 개발 환경에서 다음을 실행하여 수행합니다.
gcloud auth application-default login다른 환경의 경우 애플리케이션 기본 사용자 인증 정보 문서를 참고하세요.
또한 계정에 Vertex AI 사용자 IAM 역할 (
roles/aiplatform.user)이 부여되었는지 확인합니다. Vertex AI 액세스 제어 문서를 참고하세요.
용도
생성형 AI 모델
이 플러그인은 지원되는 생성형 AI 모델에 대한 참조를 정적으로 내보냅니다.
import { gemini15Flash, gemini15Pro, imagen3 } from '@genkit-ai/vertexai';
이러한 참조를 사용하여 ai.generate()가 사용하는 모델을 지정할 수 있습니다.
const ai = genkit({
plugins: [vertexAI({ location: 'us-central1' })],
});
const llmResponse = await ai.generate({
model: gemini15Flash,
prompt: 'What should I do when I visit Melbourne?',
});
이 플러그인은 Google 검색 또는 자체 데이터를 사용하여 Gemini 텍스트 응답을 기반으로 하는 기능도 지원합니다.
예:
const ai = genkit({
plugins: [vertexAI({ location: 'us-central1' })],
});
await ai.generate({
model: gemini15Flash,
prompt: '...',
config: {
googleSearchRetrieval: {
disableAttribution: true,
}
vertexRetrieval: {
datastore: {
projectId: 'your-cloud-project',
location: 'us-central1',
collection: 'your-collection',
},
disableAttribution: true,
}
}
})
이 플러그인은 Gecko 텍스트 임베딩 모델에 대한 참조를 정적으로 내보냅니다.
import { textEmbedding004 } from '@genkit-ai/vertexai';
이 참조를 사용하여 색인 생성기 또는 검색 도구가 사용하는 삽입자를 지정할 수 있습니다. 예를 들어 Chroma DB를 사용하는 경우 다음과 같습니다.
const ai = genkit({
plugins: [
chroma([
{
embedder: textEmbedding004,
collectionName: 'my-collection',
},
]),
],
});
또는 직접 삽입을 생성할 수 있습니다.
const ai = genkit({
plugins: [vertexAI({ location: 'us-central1' })],
});
const embedding = await ai.embed({
embedder: textEmbedding004,
content: 'How many widgets do you have in stock?',
});
Imagen3 모델을 사용하면 사용자 프롬프트에서 이미지를 생성할 수 있습니다.
import { imagen3 } from '@genkit-ai/vertexai';
const ai = genkit({
plugins: [vertexAI({ location: 'us-central1' })],
});
const response = await ai.generate({
model: imagen3,
output: { format: 'media' },
prompt: 'a banana riding a bicycle',
});
return response.media();
기존 이미지의 고급 편집도 가능합니다.
const ai = genkit({
plugins: [vertexAI({ location: 'us-central1' })],
});
const baseImg = fs.readFileSync('base.png', { encoding: 'base64' });
const maskImg = fs.readFileSync('mask.png', { encoding: 'base64' });
const response = await ai.generate({
model: imagen3,
output: { format: 'media' },
prompt: [
{ media: { url: `data:image/png;base64,${baseImg}` }},
{
media: { url: `data:image/png;base64,${maskImg}` },
metadata: { type: 'mask' },
},
{ text: 'replace the background with foo bar baz' },
],
config: {
editConfig: {
editMode: 'outpainting',
},
},
});
return response.media();
자세한 옵션은 Imagen 모델 문서를 참고하세요.
Vertex AI Model Garden의 Anthropic Claude 3
Vertex AI Model Garden의 Claude 3 모델 (haiku, sonnet 또는 opus)에 액세스할 수 있는 경우 Genkit에서 이를 사용할 수 있습니다.
다음은 Vertex AI Model Garden 모델을 사용 설정하기 위한 샘플 구성입니다.
import { genkit } from 'genkit';
import {
claude3Haiku,
claude3Sonnet,
claude3Opus,
vertexAIModelGarden,
} from '@genkit-ai/vertexai/modelgarden';
const ai = genkit({
plugins: [
vertexAIModelGarden({
location: 'us-central1',
models: [claude3Haiku, claude3Sonnet, claude3Opus],
}),
],
});
그런 다음 일반 모델로 사용합니다.
const llmResponse = await ai.generate({
model: claude3Sonnet,
prompt: 'What should I do when I visit Melbourne?',
});
Vertex AI Model Garden의 Llama 3.1 405b
먼저 Vertex AI Model Garden에서 Llama 3.1 API 서비스를 사용 설정해야 합니다.
다음은 Vertex AI 플러그인의 Llama 3.1 405b 샘플 구성입니다.
import { genkit } from 'genkit';
import { llama31, vertexAIModelGarden } from '@genkit-ai/vertexai/modelgarden';
const ai = genkit({
plugins: [
vertexAIModelGarden({
location: 'us-central1',
models: [llama31],
}),
],
});
그런 다음 일반 모델로 사용합니다.
const llmResponse = await ai.generate({
model: llama31,
prompt: 'Write a function that adds two numbers together',
});
Vertex AI Model Garden의 Mistral 모델
Vertex AI Model Garden의 Mistral 모델 (Mistral Large, Mistral Nemo 또는 Codestral)에 액세스할 수 있는 경우 Genkit에서 사용할 수 있습니다.
다음은 Vertex AI Model Garden 모델을 사용 설정하기 위한 샘플 구성입니다.
import { genkit } from 'genkit';
import {
mistralLarge,
mistralNemo,
codestral,
vertexAIModelGarden,
} from '@genkit-ai/vertexai/modelgarden';
const ai = genkit({
plugins: [
vertexAIModelGarden({
location: 'us-central1',
models: [mistralLarge, mistralNemo, codestral],
}),
],
});
그런 다음 일반 모델로 사용합니다.
const llmResponse = await ai.generate({
model: mistralLarge,
prompt: 'Write a function that adds two numbers together',
config: {
version: 'mistral-large-2411', // Optional: specify model version
temperature: 0.7, // Optional: control randomness (0-1)
maxOutputTokens: 1024, // Optional: limit response length
topP: 0.9, // Optional: nucleus sampling parameter
stopSequences: ['###'], // Optional: stop generation at sequences
}
});
모델은 다음을 지원합니다.
- mistralLarge: 함수 호출 기능이 있는 최신 Mistral 대형 모델
- mistralNemo: 효율성과 속도에 최적화된 모델
- codestral: 코드 생성 작업에 특화된 모델
각 모델은 스트리밍 응답과 함수 호출을 지원합니다.
const response = await ai.generateStream({
model: mistralLarge,
prompt: 'What should I cook tonight?',
tools: ['recipe-finder'],
config: {
version: 'mistral-large-2411',
temperature: 1,
},
});
for await (const chunk of response.stream) {
console.log(chunk.text);
}
평가자
Vertex AI Rapid Evaluation의 평가자를 사용하려면 vertexAI 플러그인 구성에 evaluation 블록을 추가합니다.
import { genkit } from 'genkit';
import {
vertexAIEvaluation,
VertexAIEvaluationMetricType,
} from '@genkit-ai/vertexai/evaluation';
const ai = genkit({
plugins: [
vertexAIEvaluation({
location: 'us-central1',
metrics: [
VertexAIEvaluationMetricType.SAFETY,
{
type: VertexAIEvaluationMetricType.ROUGE,
metricSpec: {
rougeType: 'rougeLsum',
},
},
],
}),
],
});
위의 구성은 Safety 및 ROUGE 측정항목의 평가자를 추가합니다. 이 예에서는 두 가지 접근 방식을 보여줍니다. Safety 측정항목은 기본 사양을 사용하는 반면 ROUGE 측정항목은 루즈 유형을 rougeLsum로 설정하는 맞춤 사양을 제공합니다.
두 평가 도구는 호환되는 데이터 세트(output 및 reference 필드가 있는 데이터 세트)와 함께 genkit eval:run 명령어를 사용하여 실행할 수 있습니다. Safety 평가자는 output만 있으면 되므로 genkit eval:flow -e vertexai/safety 명령어를 사용하여 실행할 수도 있습니다.
색인 생성기 및 검색기
Genkit Vertex AI 플러그인에는 Vertex AI 벡터 검색 서비스의 지원을 받는 색인 생성기 및 검색기 구현이 포함되어 있습니다.
RAG 구현에서 색인 생성기와 검색기가 사용되는 방식은 검색 증강 생성 페이지를 참고하세요.
Vertex AI Vector Search 서비스는 선택한 문서 저장소와 함께 작동하는 문서 색인입니다. 문서 저장소에는 문서의 콘텐츠가 포함되며 Vertex AI Vector Search 색인에는 각 문서의 벡터 임베딩과 문서 저장소의 문서 참조가 포함됩니다. Vertex AI 벡터 검색 서비스에서 문서 색인을 생성하면 검색 쿼리에 응답하여 문서 저장소에 색인 목록을 생성할 수 있습니다.
Vertex AI 플러그인이 제공하는 색인 생성기 및 검색기 구현은 Cloud Firestore 또는 BigQuery를 문서 저장소로 사용합니다. 이 플러그인에는 다른 문서 저장소를 지원하기 위해 구현할 수 있는 인터페이스도 포함되어 있습니다.
Vertex AI 벡터 검색을 사용하려면 다음 단계를 따르세요.
- 임베딩 모델을 선택합니다. 이 모델은 텍스트에서 벡터 임베딩을 생성합니다. 고급 사용자는 특정 데이터 세트에 최적화된 임베딩 모델을 사용할 수 있지만, 대부분의 사용자에게는 Vertex AI의
text-embedding-004모델이 영어 텍스트에 적합하고text-multilingual-embedding-002모델이 다국어 텍스트에 적합합니다. Google Cloud 콘솔의 벡터 검색 섹션에서 새 색인을 만듭니다. 가장 중요한 설정은 다음과 같습니다.
- 측정기준: 선택한 임베딩 모델에서 생성된 벡터의 차원을 지정합니다.
text-embedding-004및text-multilingual-embedding-002모델은 768차원의 벡터를 생성합니다. - 업데이트 방법: 스트리밍 업데이트를 선택합니다.
색인을 만든 후 표준 (공개) 엔드포인트에 배포합니다.
- 측정기준: 선택한 임베딩 모델에서 생성된 벡터의 차원을 지정합니다.
사용하려는 문서 저장소의 문서 색인 생성기 및 검색 도구를 가져옵니다.
Cloud Firestore
import { getFirestoreDocumentIndexer, getFirestoreDocumentRetriever } from '@genkit-ai/vertexai/vectorsearch'; import { initializeApp } from 'firebase-admin/app'; import { getFirestore } from 'firebase-admin/firestore'; initializeApp({ projectId: PROJECT_ID }); const db = getFirestore(); const firestoreDocumentRetriever = getFirestoreDocumentRetriever(db, FIRESTORE_COLLECTION); const firestoreDocumentIndexer = getFirestoreDocumentIndexer(db, FIRESTORE_COLLECTION);BigQuery
import { getBigQueryDocumentIndexer, getBigQueryDocumentRetriever } from '@genkit-ai/vertexai/vectorsearch'; import { BigQuery } from '@google-cloud/bigquery'; const bq = new BigQuery({ projectId: PROJECT_ID }); const bigQueryDocumentRetriever = getBigQueryDocumentRetriever(bq, BIGQUERY_TABLE, BIGQUERY_DATASET); const bigQueryDocumentIndexer = getBigQueryDocumentIndexer(bq, BIGQUERY_TABLE, BIGQUERY_DATASET);기타
다른 문서 저장소를 지원하려면
DocumentRetriever및DocumentIndexer의 자체 구현을 제공하면 됩니다.const myDocumentRetriever = async (neighbors) => { // Return the documents referenced by `neighbors`. // ... } const myDocumentIndexer = async (documents) => { // Add `documents` to storage. // ... }예를 보려면 로컬 파일이 포함된 샘플 Vertex AI 플러그인 검색기 및 색인 생성기를 참고하세요.
vertexAI플러그인 구성에vectorSearchOptions블록을 추가합니다.import { genkit } from 'genkit'; import { textEmbedding004 } from '@genkit-ai/vertexai'; import { vertexAIVectorSearch } from '@genkit-ai/vertexai/vectorsearch'; const ai = genkit({ plugins: [ vertexAIVectorSearch({ projectId: PROJECT_ID, location: LOCATION, vectorSearchOptions: [ { indexId: VECTOR_SEARCH_INDEX_ID, indexEndpointId: VECTOR_SEARCH_INDEX_ENDPOINT_ID, deployedIndexId: VECTOR_SEARCH_DEPLOYED_INDEX_ID, publicDomainName: VECTOR_SEARCH_PUBLIC_DOMAIN_NAME, documentRetriever: firestoreDocumentRetriever, documentIndexer: firestoreDocumentIndexer, embedder: textEmbedding004, }, ], }), ], });첫 번째 단계에서 선택한 삽입 도구와 이전 단계에서 만든 문서 색인 생성기 및 검색 도구를 제공합니다.
앞서 만든 백터 검색 색인을 사용하도록 플러그인을 구성하려면 Google Cloud 콘솔의 백터 검색 섹션에서 찾을 수 있는 여러 값을 제공해야 합니다.
이제 모든 항목이 구성되었으므로 Genkit 애플리케이션에서 색인 생성기와 검색 도구를 사용할 수 있습니다.
import { vertexAiIndexerRef, vertexAiRetrieverRef, } from '@genkit-ai/vertexai/vectorsearch'; // ... inside your flow function: await ai.index({ indexer: vertexAiIndexerRef({ indexId: VECTOR_SEARCH_INDEX_ID, }), documents, }); const res = await ai.retrieve({ retriever: vertexAiRetrieverRef({ indexId: VECTOR_SEARCH_INDEX_ID, }), query: queryDocument, });
다음에 관한 코드 샘플을 참고하세요.
컨텍스트 캐싱
Vertex AI Genkit 플러그인은 컨텍스트 캐싱을 지원합니다. 이를 통해 모델은 이전에 캐시된 콘텐츠를 재사용하여 대규모 콘텐츠를 처리할 때 토큰 사용을 최적화할 수 있습니다. 이 기능은 대화형 흐름이나 모델이 여러 요청에서 일관되게 대규모 콘텐츠를 참조하는 시나리오에 특히 유용합니다.
컨텍스트 캐싱 사용 방법
컨텍스트 캐싱을 사용 설정하려면 모델에서 이를 지원하는지 확인합니다. 예를 들어 gemini15Flash 및 gemini15Pro는 컨텍스트 캐싱을 지원하는 모델이며 버전 번호 001를 지정해야 합니다.
다음과 같이 애플리케이션에서 캐싱 메커니즘을 정의할 수 있습니다.
const ai = genkit({
plugins: [googleAI()],
});
const llmResponse = await ai.generate({
messages: [
{
role: 'user',
content: [{ text: 'Here is the relevant text from War and Peace.' }],
},
{
role: 'model',
content: [
{
text: 'Based on War and Peace, here is some analysis of Pierre Bezukhov’s character.',
},
],
metadata: {
cache: {
ttlSeconds: 300, // Cache this message for 5 minutes
},
},
},
],
model: gemini15Flash,
prompt: 'Describe Pierre’s transformation throughout the novel.',
});
이 설정에서 다음을 수행할 수 있습니다.
- messages: 대화 기록을 전달할 수 있습니다.
- metadata.cache.ttlSeconds: 특정 응답을 캐시하는 TTL (수명)을 지정합니다.
예: 컨텍스트를 사용하여 긴 텍스트 활용
전쟁과 평화 또는 반지의 제왕과 같이 긴 문서를 참조하는 애플리케이션의 경우 캐시된 컨텍스트를 재사용하도록 쿼리를 구성할 수 있습니다.
const textContent = await fs.readFile('path/to/war_and_peace.txt', 'utf-8');
const llmResponse = await ai.generate({
messages: [
{
role: 'user',
content: [{ text: textContent }], // Include the large text as context
},
{
role: 'model',
content: [
{
text: 'This analysis is based on the provided text from War and Peace.',
},
],
metadata: {
cache: {
ttlSeconds: 300, // Cache the response to avoid reloading the full text
},
},
},
],
model: gemini15Flash,
prompt: 'Analyze the relationship between Pierre and Natasha.',
});
컨텍스트 캐싱의 이점
- 성능 개선: 대규모 입력을 반복적으로 처리할 필요가 줄어듭니다.
- 비용 효율성: 중복 데이터에 대한 API 사용을 줄여 토큰 소비를 최적화합니다.
- 지연 시간 개선: 반복되거나 관련된 쿼리의 응답 속도를 높입니다.
컨텍스트 캐싱에 지원되는 모델
gemini15Flash 및 gemini15Pro와 같은 특정 모델만 컨텍스트 캐싱을 지원하며 현재 버전 번호 001에서만 지원됩니다. 지원되지 않는 모델을 사용하면 캐싱을 적용할 수 없다는 오류가 발생합니다.
추가 자료
Vertex AI의 컨텍스트 캐싱에 관한 자세한 내용은 문서를 참고하세요.