Google GenAI 텍스트 임베딩

Google GenAI 텍스트 임베딩 (Google GenAI Text Embeddings)

Google GenAI Embeddings API는 Gemini Developer API 또는 Vertex AI를 통해 Google의 임베딩 모델을 사용해 텍스트 임베딩을 생성해요. 이 문서에서는 Google GenAI 텍스트 임베딩 API를 사용해서 텍스트 임베딩을 만드는 방법을 설명해요. 이 글에서는 인증 모드, 프로퍼티 설정, 태스크 타입, 차원 축소, 그리고 Vertex AI 텍스트 임베딩에서의 마이그레이션까지 알아볼게요.

출처: 문서

본문

Google GenAI Embeddings API는 Gemini Developer API 또는 Vertex AI를 통해 Google의 임베딩 모델을 사용해 텍스트 임베딩 생성을 제공해요. 이 문서는 Google GenAI 텍스트 임베딩 API를 사용해 텍스트 임베딩을 만드는 방법을 설명해요.

Google GenAI 텍스트 임베딩 API는 밀집 벡터 표현(dense vector representation)을 사용해요. 단어를 숫자로 직접 매핑하는 경향이 있는 희소 벡터(sparse vector)와 달리, 밀집 벡터는 텍스트 조각의 의미를 더 잘 표현하도록 설계됐어요. 생성형 AI에서 밀집 벡터 임베딩을 사용하는 이점은, 직접적인 단어나 구문 일치를 검색하는 대신 쿼리의 의미와 일치하는 구절을 더 잘 검색할 수 있다는 점이에요. 구절이 같은 언어를 사용하지 않아도 말이죠.

__ 현재 Google GenAI SDK는 텍스트 임베딩만 지원해요. 멀티모달 임베딩 지원은 진행 중이며, SDK에서 사용 가능해지면 추가될 예정이에요.

이 구현은 두 가지 인증 모드를 제공해요:

  • Gemini Developer API : 빠른 프로토타이핑과 개발을 위해 API 키 사용

  • Vertex AI : 엔터프라이즈 기능과 함께 프로덕션 배포를 위해 Google Cloud 자격 증명 사용

Prerequisites

다음 인증 방법 중 하나를 선택하세요:

Option 1: Gemini Developer API (API Key)

  • Google AI Studio에서 API 키를 얻으세요

  • API 키를 환경 변수나 애플리케이션 프로퍼티로 설정하세요

Option 2: Vertex AI (Google Cloud)

  • 운영체제에 맞는 gcloud CLI를 설치하세요.

  • 다음 명령을 실행해 인증하세요. PROJECT_ID를 Google Cloud 프로젝트 ID로, ACCOUNT를 Google Cloud 사용자 이름으로 바꾸세요.

    gcloud config set project <PROJECT_ID> && gcloud auth application-default login

Add Repositories and BOM

Spring AI 아티팩트는 Maven Central과 Spring Snapshot 저장소에 게시돼요. 빌드 시스템에 이러한 저장소를 추가하려면 Artifact Repositories 섹션을 참고하세요.

의존성 관리를 돕기 위해 Spring AI는 프로젝트 전체에서 일관된 Spring AI 버전을 사용하도록 보장하는 BOM(bill of materials)을 제공해요. 빌드 시스템에 Spring AI BOM을 추가하려면 Dependency Management 섹션을 참고하세요.

Auto-configuration

__ Spring AI 자동 설정과 스타터 모듈 아티팩트 이름에 큰 변경이 있었어요. 자세한 내용은 upgrade notes를 참고해주세요.

Spring AI는 Google GenAI Embedding Model에 대한 Spring Boot 자동 설정을 제공해요. 활성화하려면 프로젝트의 Maven pom.xml 파일에 다음 의존성을 추가하세요:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-google-genai-embedding</artifactId>
</dependency>

또는 Gradle build.gradle 빌드 파일에 추가할 수도 있어요:

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-google-genai-embedding'
}
__ 빌드 파일에 Spring AI BOM을 추가하려면 Dependency Management 섹션을 참고해주세요.

Embedding Properties

Connection Properties

프리픽스 spring.ai.google.genai.embedding은 Google GenAI Embedding API에 연결할 수 있게 해주는 프로퍼티 프리픽스예요.

__ 연결 프로퍼티는 Google GenAI Chat 모듈과 공유돼요. chat과 embeddings를 모두 사용한다면 spring.ai.google.genai 프리픽스(chat용) 또는 spring.ai.google.genai.embedding 프리픽스(embeddings용) 중 하나로 연결을 한 번만 구성하면 돼요.
Property Description Default
spring.ai.google.genai.embedding.api-key Gemini Developer API용 API 키. 제공되면 클라이언트는 Vertex AI 대신 Gemini Developer API를 사용해요. -
spring.ai.google.genai.embedding.project-id Google Cloud Platform 프로젝트 ID (Vertex AI 모드에 필요) -
spring.ai.google.genai.embedding.location Google Cloud 리전 (Vertex AI 모드에 필요) -
spring.ai.google.genai.embedding.credentials-uri Google Cloud 자격 증명 URI. 제공되면 인증을 위한 GoogleCredentials 인스턴스를 만드는 데 사용돼요. -
__ 임베딩 자동 설정의 활성화/비활성화는 이제 프리픽스 spring.ai.model.embedding이 붙은 최상위 프로퍼티로 설정해요. 활성화하려면 spring.ai.model.embedding.text=google-genai (기본값으로 활성화됨). 비활성화하려면 spring.ai.model.embedding.text=none (또는 google-genai와 일치하지 않는 어떤 값). 이 변경은 여러 모델의 설정을 허용하기 위한 것이에요.

Text Embedding Properties

프리픽스 spring.ai.google.genai.embedding.text는 Google GenAI 텍스트 임베딩의 임베딩 모델 구현을 구성할 수 있게 해주는 프로퍼티 프리픽스예요.

Property Description Default
spring.ai.model.embedding.text Google GenAI Embedding API 모델 활성화. google-genai
spring.ai.google.genai.embedding.text.model 사용할 Google GenAI Text Embedding 모델. 지원 모델에는 text-embedding-004와 text-multilingual-embedding-002가 있어요 text-embedding-004
spring.ai.google.genai.embedding.text.task-type 더 나은 품질의 임베딩을 생성하도록 모델을 돕기 위한 의도된 다운스트림 애플리케이션. 사용 가능한 task-types: RETRIEVAL_QUERY, RETRIEVAL_DOCUMENT, SEMANTIC_SIMILARITY, CLASSIFICATION, CLUSTERING, QUESTION_ANSWERING, FACT_VERIFICATION RETRIEVAL_DOCUMENT
spring.ai.google.genai.embedding.text.title 선택적 제목, task_type=RETRIEVAL_DOCUMENT에서만 유효. -
spring.ai.google.genai.embedding.text.dimensions 결과 출력 임베딩이 가져야 하는 차원 수. 모델 버전 004 이상에서 지원돼요. 예를 들어 저장 최적화를 위해 임베딩 크기를 줄이는 데 이 매개변수를 사용할 수 있어요. -
spring.ai.google.genai.embedding.text.auto-truncate true로 설정하면 입력 텍스트가 잘려요(truncate). false로 설정하면 입력 텍스트가 모델이 지원하는 최대 길이보다 길 때 오류가 반환돼요. true

Sample Controller

새 Spring Boot 프로젝트를 만들고, pom(또는 gradle) 의존성에 spring-ai-starter-model-google-genai-embedding을 추가하세요.

src/main/resources 디렉터리 아래에 application.properties 파일을 추가해 Google GenAI 임베딩 모델을 활성화하고 구성해요:

Using Gemini Developer API (API Key)

spring.ai.google.genai.embedding.api-key=YOUR_API_KEY
spring.ai.google.genai.embedding.text.model=text-embedding-004

Using Vertex AI

spring.ai.google.genai.embedding.project-id=YOUR_PROJECT_ID
spring.ai.google.genai.embedding.location=YOUR_PROJECT_LOCATION
spring.ai.google.genai.embedding.text.model=text-embedding-004

이렇게 하면 클래스에 주입할 수 있는 GoogleGenAiTextEmbeddingModel 구현이 생성돼요. 임베딩 생성을 위해 임베딩 모델을 사용하는 간단한 @Controller 클래스 예시예요:

@RestController
public class EmbeddingController {

    private final EmbeddingModel embeddingModel;

    @Autowired
    public EmbeddingController(EmbeddingModel embeddingModel) {
        this.embeddingModel = embeddingModel;
    }

    @GetMapping("/ai/embedding")
    public Map embed(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        EmbeddingResponse embeddingResponse = this.embeddingModel.embedForResponse(List.of(message));
        return Map.of("embedding", embeddingResponse);
    }
}

Manual Configuration

GoogleGenAiTextEmbeddingModel은 EmbeddingModel을 구현해요.

프로젝트의 Maven pom.xml 파일에 spring-ai-google-genai-embedding 의존성을 추가하세요:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-google-genai-embedding</artifactId>
</dependency>

또는 Gradle build.gradle 빌드 파일에 추가할 수도 있어요:

dependencies {
    implementation 'org.springframework.ai:spring-ai-google-genai-embedding'
}
__ 빌드 파일에 Spring AI BOM을 추가하려면 Dependency Management 섹션을 참고해주세요.

다음으로 GoogleGenAiTextEmbeddingModel을 만들고 텍스트 임베딩에 사용해요:

Using API Key

GoogleGenAiEmbeddingConnectionDetails connectionDetails =
    GoogleGenAiEmbeddingConnectionDetails.builder()
        .apiKey(System.getenv("GOOGLE_API_KEY"))
        .build();

GoogleGenAiTextEmbeddingOptions options = GoogleGenAiTextEmbeddingOptions.builder()
    .model(GoogleGenAiTextEmbeddingOptions.DEFAULT_MODEL_NAME)
    .taskType(TaskType.RETRIEVAL_DOCUMENT)
    .build();

var embeddingModel = new GoogleGenAiTextEmbeddingModel(connectionDetails, options);

EmbeddingResponse embeddingResponse = embeddingModel
	.embedForResponse(List.of("Hello World", "World is big and salvation is near"));

Using Vertex AI

GoogleGenAiEmbeddingConnectionDetails connectionDetails =
    GoogleGenAiEmbeddingConnectionDetails.builder()
        .projectId(System.getenv("GOOGLE_CLOUD_PROJECT"))
        .location(System.getenv("GOOGLE_CLOUD_LOCATION"))
        .build();

GoogleGenAiTextEmbeddingOptions options = GoogleGenAiTextEmbeddingOptions.builder()
    .model(GoogleGenAiTextEmbeddingOptions.DEFAULT_MODEL_NAME)
    .taskType(TaskType.RETRIEVAL_DOCUMENT)
    .build();

var embeddingModel = new GoogleGenAiTextEmbeddingModel(connectionDetails, options);

EmbeddingResponse embeddingResponse = embeddingModel
	.embedForResponse(List.of("Hello World", "World is big and salvation is near"));

Task Types

Google GenAI embeddings API는 특정 사용 사례에 맞게 임베딩을 최적화하기 위해 서로 다른 태스크 타입을 지원해요:

  • RETRIEVAL_QUERY: 검색 시스템의 검색 쿼리에 최적화

  • RETRIEVAL_DOCUMENT: 검색 시스템의 문서에 최적화

  • SEMANTIC_SIMILARITY: 텍스트 간 의미 유사도 측정에 최적화

  • CLASSIFICATION: 텍스트 분류 작업에 최적화

  • CLUSTERING: 유사한 텍스트 클러스터링에 최적화

  • QUESTION_ANSWERING: 질문-답변 시스템에 최적화

  • FACT_VERIFICATION: 사실 검증 작업에 최적화

서로 다른 태스크 타입을 사용하는 예시:

// For indexing documents
GoogleGenAiTextEmbeddingOptions docOptions = GoogleGenAiTextEmbeddingOptions.builder()
    .model("text-embedding-004")
    .taskType(TaskType.RETRIEVAL_DOCUMENT)
    .title("Product Documentation")  // Optional title for documents
    .build();

// For search queries
GoogleGenAiTextEmbeddingOptions queryOptions = GoogleGenAiTextEmbeddingOptions.builder()
    .model("text-embedding-004")
    .taskType(TaskType.RETRIEVAL_QUERY)
    .build();

Dimension Reduction

모델 버전 004 이상에서는 저장 최적화를 위해 임베딩 차원을 줄일 수 있어요:

GoogleGenAiTextEmbeddingOptions options = GoogleGenAiTextEmbeddingOptions.builder()
    .model("text-embedding-004")
    .dimensions(256)  // Reduce from default 768 to 256 dimensions
    .build();

Migration from Vertex AI Text Embeddings

현재 Vertex AI Text Embeddings 구현(spring-ai-vertex-ai-embedding)을 사용하고 있다면, 최소한의 변경으로 Google GenAI로 마이그레이션할 수 있어요:

Key Differences:

  1. SDK : Google GenAI는 Vertex AI SDK 대신 새 com.google.genai.Client를 사용해요

  2. Authentication : API 키와 Google Cloud 자격 증명(Vertex AI 모드)을 모두 지원해요

  3. Package Names : 클래스는 org.springframework.ai.vertexai.embedding 대신 org.springframework.ai.google.genai.text에 있어요

  4. Property Prefix : spring.ai.vertex.ai.embedding 대신 spring.ai.google.genai.embedding을 사용해요

  5. Connection Details : VertexAiEmbeddingConnectionDetails 대신 GoogleGenAiEmbeddingConnectionDetails를 사용해요

Google GenAI는 API 키를 통한 빠른 프로토타이핑과 Google Cloud 자격 증명을 통한 Vertex AI 프로덕션 배포를 모두 지원해요.

더 알아보기 (Learn more)