Voyage AI Provider

Voyage AI Provider

patelvivekdev/voyage-ai-provider는 Voyage AI를 사용해 AI SDK에 임베딩 지원을 제공하는 커뮤니티 프로바이더예요.

출처: 문서

본문

설정

Voyage 프로바이더는 voyage-ai-provider 모듈에서 사용할 수 있어요. 다음과 같이 설치할 수 있어요:

npm install voyage-ai-provider

프로바이더 인스턴스

voyage-ai-provider에서 기본 프로바이더 인스턴스 voyage를 import 할 수 있어요:

import { voyage } from 'voyage-ai-provider';

커스텀 설정이 필요하다면 voyage-ai-provider에서 createVoyage를 import 해서 설정과 함께 프로바이더 인스턴스를 만들 수 있어요:

import { createVoyage } from 'voyage-ai-provider';

const voyage = createVoyage({
  // custom settings
});

Voyage 프로바이더 인스턴스를 커스터마이즈하기 위해 다음의 선택적 설정을 사용할 수 있어요:

  • baseURL string

    Voyage API의 기본 URL이에요. 기본 접두사는 https://api.voyageai.com/v1이에요.

  • apiKey string

    Authorization 헤더로 전송되는 API 키예요. 기본값은 VOYAGE_API_KEY 환경 변수예요.

  • headers Record<string,string>

    요청에 포함할 커스텀 헤더예요.

  • fetch (input: RequestInfo, init?: RequestInit) => Promise<Response>

    커스텀 fetch 구현이에요. 기본값은 전역 fetch 함수예요. 요청을 가로채는 미들웨어로 사용하거나, 예를 들어 테스트를 위한 커스텀 fetch 구현을 제공하는 데 사용할 수 있어요.

텍스트 임베딩 모델

.embeddingModel() 팩토리 메서드를 사용해 Voyage 임베딩 API를 호출하는 모델을 만들 수 있어요.

import { voyage } from 'voyage-ai-provider';

const embeddingModel = voyage.embeddingModel('voyage-3.5-lite');

embed 또는 embedMany 함수로 Voyage 임베딩 모델을 사용해 임베딩을 생성할 수 있어요:

import { voyage } from 'voyage-ai-provider';
import { embed } from 'ai';

const { embedding } = await embed({
  model: voyage.embeddingModel('voyage-3.5-lite'),
  value: 'sunny day at the beach',
  providerOptions: {
    voyage: {
      inputType: 'document',
    },
  },
});

Voyage 임베딩 모델은 providerOptions.voyage를 통해 전달할 수 있는 추가 프로바이더 옵션을 지원해요:

import { voyage } from 'voyage-ai-provider';
import { embed } from 'ai';

const { embedding } = await embed({
  model: voyage.embeddingModel('voyage-3.5-lite'),
  value: 'sunny day at the beach',
  providerOptions: {
    voyage: {
      inputType: 'query',
      outputDimension: 512,
    },
  },
});

다음 프로바이더 옵션을 사용할 수 있어요:

  • inputType 'query' | 'document' | 'null'

    모델에 전달되는 입력의 타입을 지정해요. 기본값은 'null'이에요.

    • 'null': inputType이 'null'이면 임베딩 모델이 입력을 직접 숫자 벡터로 변환해요.

    검색(retrieval/search) 목적이라면 'query' 또는 'document'를 사용하는 것이 권장돼요.

    • 'query': 입력이 검색 쿼리예요, 예: "Represent the query for retrieving supporting documents: ...".
    • 'document': 입력은 벡터 데이터베이스에 저장할 문서예요, 예: "Represent the document for retrieval: ...".

  • outputDimension number

    결과 출력 임베딩의 차원 수예요. 기본값은 'null'이에요.

    • 예를 들어, voyage-code-3와 voyage-3-large는 2048, 1024(기본), 512, 256을 지원해요.
    • 지원되는 값은 모델 문서를 참고하세요.

  • outputDtype 'float' | 'int8' | 'uint8' | 'binary' | 'ubinary'

    출력 임베딩의 데이터 타입이에요. 기본값은 'float'이에요.

    • 'float': 32비트 부동소수점 (모든 모델 지원).
    • 'int8', 'uint8': 8비트 정수 타입 (voyage-3-large, voyage-3.5, voyage-3.5-lite, voyage-code-3 지원).
    • 'binary', 'ubinary': 비트 패킹된 양자화 단일 비트 임베딩 값 (voyage-3-large, voyage-3.5, voyage-3.5-lite, voyage-code-3). 반환되는 리스트 길이는 outputDimension의 1/8이에요. 'binary'는 오프셋 바이너리 인코딩을 사용해요.

    자세한 내용은 FAQ: Output Data Types를 참고하세요.

  • truncation boolean

    입력 텍스트를 모델의 컨텍스트 길이에 맞게 잘라낼지 여부예요. 지정하지 않으면 기본값은 true예요.

더 많은 모델은 Voyage Library 홈페이지에서 찾을 수 있어요.

모델 기능

모델 기본 차원 컨텍스트 길이
voyage-3.5 1024 (기본), 256, 512, 2048 32,000
voyage-3.5-lite 1024 (기본), 256, 512, 2048 32,000
voyage-3-large 1024 (기본), 256, 512, 2048 32,000
voyage-3 1024 32,000
voyage-code-3 1024 (기본), 256, 512, 2048 32,000
voyage-3-lite 512 32,000
voyage-finance-2 1024 32,000
voyage-multilingual-2 1024 32,000
voyage-law-2 1024 32,000
voyage-code-2 1024 16,000

위 표는 인기 모델을 나열한 것이에요. 전체 모델 목록은 Voyage 문서를 참고하세요.

이미지 임베딩

예시 1: 이미지를 단일 임베딩으로 만들기

import { voyage, ImageEmbeddingInput } from 'voyage-ai-provider';
import { embedMany } from 'ai';

const imageModel = voyage.imageEmbeddingModel('voyage-multimodal-3');

const { embeddings } = await embedMany<ImageEmbeddingInput>({
  model: imageModel,
  values: [
    {
      image:
        'https://raw.githubusercontent.com/voyage-ai/voyage-multimodal-3/refs/heads/main/images/banana_200_x_200.jpg',
    },
    {
      image: 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA...',
    },
  ],
  // or you can pass the array of images url and base64 string directly
  // values: [
  //   'https://raw.githubusercontent.com/voyage-ai/voyage-multimodal-3/refs/heads/main/images/banana_200_x_200.jpg',
  //   'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA...',
  // ],
});

예시 2: 여러 이미지를 단일 임베딩으로 만들기

import { voyage, ImageEmbeddingInput } from 'voyage-ai-provider';
import { embedMany } from 'ai';

const imageModel = voyage.imageEmbeddingModel('voyage-multimodal-3');

const { embeddings } = await embedMany<ImageEmbeddingInput>({
  model: imageModel,
  values: [
    {
      image: [
        'https://raw.githubusercontent.com/voyage-ai/voyage-multimodal-3/refs/heads/main/images/banana_200_x_200.jpg',
        'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA...',
      ],
    },
  ],
});

이미지 URL을 찾을 수 없다는 오류가 나면 이미지를 base64로 변환해 base64 데이터 URL을 image 배열로 전달하세요. 값은 data:[mediatype];base64,<data> 형식의 Base64 인코딩 이미지여야 해요. 지원되는 미디어 타입: image/png, image/jpeg, image/webp, image/gif.

멀티모달 임베딩

예시 1: 여러 텍스트와 이미지를 단일 임베딩으로 만들기

import { voyage, MultimodalEmbeddingInput } from 'voyage-ai-provider';
import { embedMany } from 'ai';

const multimodalModel = voyage.multimodalEmbeddingModel('voyage-multimodal-3');

const { embeddings } = await embedMany<MultimodalEmbeddingInput>({
  model: multimodalModel,
  values: [
    {
      text: ['Hello, world!', 'This is a banana'],
      image: [
        'https://raw.githubusercontent.com/voyage-ai/voyage-multimodal-3/refs/heads/main/images/banana_200_x_200.jpg',
      ],
    },
    {
      text: ['Hello, coders!', 'This is a coding test'],
      image: ['data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA...'],
    },
  ],
});

values 목록에는 다음 제약이 적용돼요:

  • 목록에는 1,000개 이하의 값만 포함되어야 해요.
  • 각 이미지는 1,600만 픽셀을 넘거나 20MB보다 크면 안 돼요.
  • 이미지의 560픽셀마다 1토큰으로 계산할 때, 목록의 각 입력은 32,000토큰을 넘지 않아야 하고, 모든 입력의 총 토큰 수는 320,000을 넘지 않아야 해요.

Voyage 멀티모달 임베딩 모델은 providerOptions.voyage를 통해 전달할 수 있는 추가 프로바이더 옵션을 지원해요:

import { voyage, MultimodalEmbeddingInput } from 'voyage-ai-provider';
import { embedMany } from 'ai';

const multimodalModel = voyage.multimodalEmbeddingModel('voyage-multimodal-3');

const { embeddings } = await embedMany<MultimodalEmbeddingInput>({
  model: multimodalModel,
  values: [
    {
      text: ['Hello, world!'],
      image: ['data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA...'],
    },
  ],
  providerOptions: {
    voyage: {
      inputType: 'query',
      outputEncoding: 'base64',
      truncation: true,
    },
  },
});

다음 프로바이더 옵션을 사용할 수 있어요:

  • inputType 'query' | 'document'

    모델에 전달되는 입력의 타입을 지정해요. 기본값은 'query'예요.

    inputType이 'query'나 'document'로 지정되면, Voyage는 입력을 벡터화하기 전에 자동으로 프롬프트를 앞에 붙여 검색(retrieval/search) 작업에 맞는 벡터를 만들어요:

    • 'query': "Represent the query for retrieving supporting documents: "를 앞에 붙임
    • 'document': "Represent the document for retrieval: "를 앞에 붙임

  • outputEncoding 'base64'

    결과 출력 임베딩의 데이터 인코딩이에요. 기본값은 null (32비트 부동소수점 목록)이에요.

    • null이면 임베딩을 부동소수점(float32) 목록으로 반환해요.
    • 'base64'이면 임베딩을 단정밀도 부동소수점의 Base64 인코딩 NumPy 배열로 반환해요.

    자세한 내용은 FAQ: Output Data Types를 참고하세요.

  • truncation boolean

    입력을 모델의 컨텍스트 길이에 맞게 잘라낼지 여부예요. 지정하지 않으면 기본값은 true예요.

모델 기능

모델 컨텍스트 길이 (토큰) 임베딩 차원
voyage-multimodal-3 32,000 1024

더 알아보기 (Learn more)