텍스트 임베딩 API는 텍스트 데이터를 숫자 벡터로 변환합니다. 이러한 벡터 표현은 표현이 나타내는 단어의 시맨틱 의미와 컨텍스트를 캡처하도록 설계되었습니다.
지원되는 모델:
영어 모델 | 다국어 모델 |
---|---|
textembedding-gecko@001 |
textembedding-gecko-multilingual@001 |
textembedding-gecko@003 |
text-multilingual-embedding-002 |
text-embedding-004 |
구문
curl
PROJECT_ID = PROJECT_ID REGION = us-central1 MODEL_ID = MODEL_ID curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}/publishers/google/models/${MODEL_ID}:predict -d \ '{ "instances": [ ... ], "parameters": { ... } }'
Python
PROJECT_ID = PROJECT_ID REGION = us-central1 MODEL_ID = MODEL_ID import vertexai from vertexai.language_models import TextEmbeddingModel vertexai.init(project=PROJECT_ID, location=REGION) model = TextEmbeddingModel.from_pretrained(MODEL_ID) embeddings = model.get_embeddings(...)
매개변수 목록
매개변수 | |
---|---|
|
각 인스턴스는 임베딩할 단일 텍스트를 나타냅니다. |
|
임베딩을 생성하려는 텍스트입니다. |
|
선택사항: true로 설정하면 입력 텍스트가 잘립니다. false로 설정하면 입력 텍스트가 모델에서 지원하는 최대 길이보다 길경우 오류가 반환됩니다. 기본값은 true입니다. |
|
선택사항: 출력 임베딩 크기를 지정하는 데 사용됩니다. 설정하면 출력 임베딩이 지정된 크기로 잘립니다. |
요청 본문
{
"instances": [
{
"task_type": "RETRIEVAL_DOCUMENT",
"title": "document title",
"content": "I would like embeddings for this text!"
},
]
}
매개변수 | |
---|---|
|
임베딩을 생성하려는 텍스트입니다. |
|
선택사항: 모델이 더 나은 임베딩을 생성할 수 있도록 의도된 다운스트림 애플리케이션을 전달하는 데 사용됩니다. 다음 값 중 하나여야 합니다.
textembedding-gecko@001 모델에는 |
|
(선택사항) 모델이 더 나은 임베딩을 생성하도록 지원하는 데 사용됩니다.
|
taskType
다음 표에서는 task_type
매개변수 값과 사용 사례를 설명합니다.
task_type |
설명 |
---|---|
RETRIEVAL_QUERY |
지정된 텍스트가 검색 또는 가져오기 설정의 쿼리임을 지정합니다. |
RETRIEVAL_DOCUMENT |
지정된 텍스트가 검색 또는 가져오기 설정의 문서임을 지정합니다. |
SEMANTIC_SIMILARITY |
지정된 텍스트를 시맨틱 텍스트 유사성(STS)에 사용하도록 지정합니다. |
CLASSIFICATION |
분류에 임베딩을 사용하도록 지정합니다. |
CLUSTERING |
클러스터링에 임베딩을 사용하도록 지정합니다. |
QUESTION_ANSWERING |
질문에 답변하는 데 쿼리 임베딩을 사용하도록 지정합니다. 문서에는 RETRIEVAL_DOCUMENT를 사용합니다. |
FACT_VERIFICATION |
사실 확인에 쿼리 임베딩을 사용하도록 지정합니다. |
검색 태스크:
쿼리: task_type=RETRIEVAL_QUERY
을 사용하여 입력 텍스트가 검색어임을 나타냅니다.
Corpus: task_type=RETRIEVAL_DOCUMENT
를 사용하여 입력 텍스트가 검색 중인 문서 컬렉션의 일부임을 나타냅니다.
유사성 태스크:
시맨틱 유사성: 두 입력 텍스트 모두에 task_type= SEMANTIC_SIMILARITY
를 사용하여 전반적인 의미 유사성을 평가합니다.
응답 본문
{
"predictions": [
{
"embeddings": {
"statistics": {
"truncated": boolean,
"token_count": integer
},
"values": [ number ]
}
}
]
}
응답 요소 | 설명 |
---|---|
embeddings |
입력 텍스트에서 생성된 결과입니다. |
statistics |
입력 텍스트에서 계산된 통계입니다. |
truncated |
입력 텍스트가 최대 허용 토큰보다 길고 잘렸는지 여부를 나타냅니다. |
tokenCount |
입력 텍스트의 토큰 수입니다. |
values |
values 필드에는 입력 텍스트의 단어에 해당하는 임베딩 벡터가 포함됩니다. |
샘플 응답
{
"predictions": [
{
"embeddings": {
"values": [
0.0058424929156899452,
0.011848051100969315,
0.032247550785541534,
-0.031829461455345154,
-0.055369812995195389,
...
],
"statistics": {
"token_count": 4,
"truncated": false
}
}
}
]
}
예시
텍스트 문자열 삽입
기본 사용 사례
다음 예시에서는 텍스트 문자열의 임베딩을 가져오는 방법을 보여줍니다.
REST
환경을 설정하면 REST를 사용하여 텍스트 프롬프트를 테스트할 수 있습니다. 다음 샘플은 요청을 게시자 모델 엔드포인트에 전송합니다.
요청 데이터를 사용하기 전에 다음을 바꿉니다.
- PROJECT_ID: 프로젝트 ID
- TEXT: 임베딩을 생성하려는 텍스트입니다. 한도:
textembedding-gecko@001
를 제외한 모든 모델에 대해 텍스트당 최대 2,048개의 토큰으로 구성된 텍스트 5개입니다.textembedding-gecko@001
의 최대 입력 토큰 길이는 3072입니다. - AUTO_TRUNCATE:
false
로 설정하면 토큰 한도를 초과하는 텍스트로 인해 요청이 실패합니다. 기본값은true
입니다.
HTTP 메서드 및 URL:
POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/text-embedding-004:predict
JSON 요청 본문:
{ "instances": [ { "content": "TEXT"} ], "parameters": { "autoTruncate": AUTO_TRUNCATE } }
요청을 보내려면 다음 옵션 중 하나를 선택합니다.
curl
요청 본문을 request.json
파일에 저장하고 다음 명령어를 실행합니다.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/text-embedding-004:predict"
PowerShell
요청 본문을 request.json
파일에 저장하고 다음 명령어를 실행합니다.
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/text-embedding-004:predict" | Select-Object -Expand Content
다음과 비슷한 JSON 응답이 수신됩니다. values
는 공간 절약을 위해 잘렸습니다.
- 응답이 완전히 생성된 후 반환되도록 요청하려면
generateContent
메서드를 사용합니다. 시청자가 지연 시간에 대해 갖는 느낌을 줄이려면streamGenerateContent
메서드를 사용하여 생성되는 응답을 스트리밍합니다. - 멀티모달 모델 ID는 메서드 앞의 URL 끝 부분에 있습니다(예:
gemini-1.5-flash
또는gemini-1.0-pro-vision
). 이 샘플은 다른 모델도 지원할 수 있습니다.
Python
Vertex AI SDK for Python을 설치하거나 업데이트하는 방법은 Vertex AI SDK for Python 설치를 참조하세요. 자세한 내용은 Python API 참고 문서를 확인하세요.
Go
이 샘플을 사용해 보기 전에 Vertex AI 빠른 시작: 클라이언트 라이브러리 사용의 Go 설정 안내를 따르세요. 자세한 내용은 Vertex AI Go API 참고 문서를 참조하세요.
Vertex AI에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
Java
이 샘플을 사용해 보기 전에 Vertex AI 빠른 시작: 클라이언트 라이브러리 사용의 Java 설정 안내를 따르세요. 자세한 내용은 Vertex AI Java API 참고 문서를 참조하세요.
Vertex AI에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
Node.js
이 샘플을 사용해 보기 전에 Vertex AI 빠른 시작: 클라이언트 라이브러리 사용의 Node.js 설정 안내를 따르세요. 자세한 내용은 Vertex AI Node.js API 참고 문서를 참조하세요.
Vertex AI에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
고급 사용 사례
다음 예시에서는 몇 가지 고급 기능을 보여줍니다.
task_type
및title
을 사용하여 임베딩 품질을 개선합니다.- 매개변수를 사용하여 API의 동작을 제어합니다.
REST
요청 데이터를 사용하기 전에 다음을 바꿉니다.
- PROJECT_ID: 프로젝트 ID
- TEXT: 임베딩을 생성하려는 텍스트입니다. 한도: 텍스트당 최대 3,072개의 토큰으로 구성된 텍스트 5개입니다.
- TASK_TYPE: 모델이 더 나은 임베딩을 생성할 수 있도록 의도된 다운스트림 애플리케이션을 전달하는 데 사용됩니다.
- TITLE: 모델이 더 나은 임베딩을 생성하도록 지원하는 데 사용됩니다.
- AUTO_TRUNCATE:
false
로 설정하면 토큰 한도를 초과하는 텍스트로 인해 요청이 실패합니다. 기본값은true
입니다. - OUTPUT_DIMENSIONALITY: 출력 임베딩 크기를 지정하는 데 사용됩니다. 설정하면 출력 임베딩이 지정된 크기로 잘립니다.
HTTP 메서드 및 URL:
POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/textembedding-gecko@003:predict
JSON 요청 본문:
{ "instances": [ { "content": "TEXT", "task_type": "TASK_TYPE", "title": "TITLE" }, ], "parameters": { "autoTruncate": AUTO_TRUNCATE, "outputDimensionality": OUTPUT_DIMENSIONALITY } }
요청을 보내려면 다음 옵션 중 하나를 선택합니다.
curl
요청 본문을 request.json
파일에 저장하고 다음 명령어를 실행합니다.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/textembedding-gecko@003:predict"
PowerShell
요청 본문을 request.json
파일에 저장하고 다음 명령어를 실행합니다.
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/textembedding-gecko@003:predict" | Select-Object -Expand Content
다음과 비슷한 JSON 응답이 수신됩니다. values
는 공간 절약을 위해 잘렸습니다.
Python
Vertex AI SDK for Python을 설치하거나 업데이트하는 방법은 Vertex AI SDK for Python 설치를 참조하세요. 자세한 내용은 Python API 참고 문서를 확인하세요.
Go
이 샘플을 사용해 보기 전에 Vertex AI 빠른 시작: 클라이언트 라이브러리 사용의 Go 설정 안내를 따르세요. 자세한 내용은 Vertex AI Go API 참고 문서를 참조하세요.
Vertex AI에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
Java
이 샘플을 사용해 보기 전에 Vertex AI 빠른 시작: 클라이언트 라이브러리 사용의 Java 설정 안내를 따르세요. 자세한 내용은 Vertex AI Java API 참고 문서를 참조하세요.
Vertex AI에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
Node.js
이 샘플을 사용해 보기 전에 Vertex AI 빠른 시작: 클라이언트 라이브러리 사용의 Node.js 설정 안내를 따르세요. 자세한 내용은 Vertex AI Node.js API 참고 문서를 참조하세요.
Vertex AI에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
지원되는 텍스트 언어
모든 텍스트 임베딩 모델은 영어 텍스트를 지원하며 이 텍스트를 기반으로 평가되었습니다. textembedding-gecko-multilingual@001
및 text-multilingual-embedding-002
모델은 추가로 다음 언어를 지원하며 다음 언어를 기반으로 평가되었습니다.
- 평가된 언어:
Arabic (ar)
,Bengali (bn)
,English (en)
,Spanish (es)
,German (de)
,Persian (fa)
,Finnish (fi)
,French (fr)
,Hindi (hi)
,Indonesian (id)
,Japanese (ja)
,Korean (ko)
,Russian (ru)
,Swahili (sw)
,Telugu (te)
,Thai (th)
,Yoruba (yo)
,Chinese (zh)
- 지원되는 언어:
Afrikaans
,Albanian
,Amharic
,Arabic
,Armenian
,Azerbaijani
,Basque
,Belarusiasn
,Bengali
,Bulgarian
,Burmese
,Catalan
,Cebuano
,Chichewa
,Chinese
,Corsican
,Czech
,Danish
,Dutch
,English
,Esperanto
,Estonian
,Filipino
,Finnish
,French
,Galician
,Georgian
,German
,Greek
,Gujarati
,Haitian Creole
,Hausa
,Hawaiian
,Hebrew
,Hindi
,Hmong
,Hungarian
,Icelandic
,Igbo
,Indonesian
,Irish
,Italian
,Japanese
,Javanese
,Kannada
,Kazakh
,Khmer
,Korean
,Kurdish
,Kyrgyz
,Lao
,Latin
,Latvian
,Lithuanian
,Luxembourgish
,Macedonian
,Malagasy
,Malay
,Malayalam
,Maltese
,Maori
,Marathi
,Mongolian
,Nepali
,Norwegian
,Pashto
,Persian
,Polish
,Portuguese
,Punjabi
,Romanian
,Russian
,Samoan
,Scottish Gaelic
,Serbian
,Shona
,Sindhi
,Sinhala
,Slovak
,Slovenian
,Somali
,Sotho
,Spanish
,Sundanese
,Swahili
,Swedish
,Tajik
,Tamil
,Telugu
,Thai
,Turkish
,Ukrainian
,Urdu
,Uzbek
,Vietnamese
,Welsh
,West Frisian
,Xhosa
,Yiddish
,Yoruba
,Zulu
.
모델 버전
정식 모델 버전을 사용하려면 모델 버전 번호를 지정합니다(예: text-embedding-004
).
각 안정화 버전은 후속 안정화 버전의 출시 날짜로부터 6개월 동안 사용 가능합니다.
다음 표에는 사용 가능한 정식 모델 버전이 포함되어 있습니다.
모델 이름 | 출시일 | 지원 중단 날짜 |
---|---|---|
text-embedding-004 | 2024년 5월 14일 | 미정 |
text-multilingual-embedding-002 | 2024년 5월 14일 | 미정 |
textembedding-gecko@003 | 2023년 12월 12일 | 2025년 5월 14일 |
textembedding-gecko-multilingual@001 | 2023년 11월 2일 | 2025년 5월 14일 |
textembedding-gecko@002 (회귀되었지만 계속 지원됨) |
2023년 11월 2일 | 2024년 12월 12일 |
textembedding-gecko@001 (회귀되었지만 계속 지원됨) |
2023년 6월 7일 | 2024년 11월 2일 |
multimodalembedding@001 | 2024년 2월 12일 | 미정 |
자세한 내용은 모델 버전 및 수명 주기를 참조하세요.
다음 단계
자세한 문서는 다음을 참조하세요.