텍스트 임베딩 API는 텍스트 데이터를 숫자 벡터로 변환합니다. 이러한 벡터 표현은 표현이 나타내는 단어의 시맨틱 의미와 컨텍스트를 캡처하도록 설계되었습니다.
지원되는 모델:
다음 모델을 사용하여 텍스트 임베딩을 가져올 수 있습니다.
모델 이름 | 설명 | 출력 측정기준 | 최대 시퀀스 길이 | 지원되는 텍스트 언어 |
---|---|---|---|---|
gemini-embedding-001 |
영어, 다국어, 코드 태스크에서의 최첨단 성능입니다. 이전의 전문 모델(예: text-embedding-005 , text-multilingual-embedding-002 )을 통합하고 각 도메인에서 더욱 우수한 성능을 얻습니다. 자세한 내용은 기술 보고서를 참조하세요. |
최대 3072 | 토큰 2048개 | 지원되는 텍스트 언어 |
text-embedding-005 |
영어 및 코드 태스크에 특화되어 있습니다. | 최대 768 | 토큰 2048개 | 영어 |
text-multilingual-embedding-002 |
다국어 태스크에 특화되어 있습니다. | 최대 768 | 토큰 2048개 | 지원되는 텍스트 언어 |
또한 우수한 임베딩 품질을 위한 gemini-embedding-001
은 최고의 성능을 제공하도록 설계된 Google의 대규모 모델입니다.
구문
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(...)
매개변수 목록
최상위 필드 | |
---|---|
|
다음 필드가 포함된 객체 목록입니다.
|
|
다음 필드가 포함된 객체입니다.
|
필드 instance 개 |
|
---|---|
|
임베딩을 생성하려는 텍스트입니다. |
|
선택사항: 모델이 더 나은 임베딩을 생성할 수 있도록 의도된 다운스트림 애플리케이션을 전달하는 데 사용됩니다. 비워두면 기본값
태스크 유형에 대한 자세한 내용은 임베딩 태스크 유형 선택을 참조하세요. |
|
선택사항: 모델이 더 나은 임베딩을 생성하도록 지원하는 데 사용됩니다.
|
task_type
다음 표에서는 task_type
파라미터 값 및 사용 사례에 대해 설명합니다.
task_type |
설명 |
---|---|
RETRIEVAL_QUERY |
지정된 텍스트가 검색 또는 가져오기 설정의 쿼리임을 지정합니다. 문서에는 RETRIEVAL_DOCUMENT를 사용합니다. |
RETRIEVAL_DOCUMENT |
지정된 텍스트가 검색 또는 가져오기 설정의 문서임을 지정합니다. |
SEMANTIC_SIMILARITY |
지정된 텍스트를 시맨틱 텍스트 유사성(STS)에 사용하도록 지정합니다. |
CLASSIFICATION |
분류에 임베딩을 사용하도록 지정합니다. |
CLUSTERING |
클러스터링에 임베딩을 사용하도록 지정합니다. |
QUESTION_ANSWERING |
질문에 답변하는 데 쿼리 임베딩을 사용하도록 지정합니다. 문서에는 RETRIEVAL_DOCUMENT를 사용합니다. |
FACT_VERIFICATION |
사실 확인에 쿼리 임베딩을 사용하도록 지정합니다. 문서에는 RETRIEVAL_DOCUMENT를 사용합니다. |
CODE_RETRIEVAL_QUERY |
Java 및 Python용 코드 검색에 쿼리 임베딩을 사용하도록 지정합니다. 문서에는 RETRIEVAL_DOCUMENT를 사용합니다. |
검색 태스크:
쿼리: task_type=RETRIEVAL_QUERY
를 사용하여 입력 텍스트가 검색어라는 것을 나타냅니다.
Corpus: task_type=RETRIEVAL_DOCUMENT
를 사용하여 입력 텍스트가 검색 중인 문서 컬렉션의 일부임을 나타냅니다.
유사성 태스크:
시맨틱 유사성: 두 입력 텍스트 모두 task_type= SEMANTIC_SIMILARITY
를 사용하여 전체 의미 유사성을 평가합니다.
필드 parameters 개 |
|
---|---|
|
선택사항: true로 설정하면 입력 텍스트가 잘립니다. false로 설정하면 입력 텍스트가 모델에서 지원하는 최대 길이보다 길경우 오류가 반환됩니다. 기본값은 true입니다. |
|
선택사항: 출력 임베딩 크기를 지정하는 데 사용됩니다. 설정하면 출력 임베딩이 지정된 크기로 잘립니다. |
요청 본문
{
"instances": [
{
"task_type": "RETRIEVAL_DOCUMENT",
"title": "document title",
"content": "I would like embeddings for this text!"
},
]
}
응답 본문
{
"predictions": [
{
"embeddings": {
"statistics": {
"truncated": boolean,
"token_count": integer
},
"values": [ number ]
}
}
]
}
대답 요소 | |
---|---|
|
다음 필드가 있는 객체 목록입니다.
|
필드 embeddings 개 |
|
---|---|
|
|
|
입력 텍스트에서 계산된 통계입니다. 다음을 포함합니다.
|
샘플 응답
{
"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입니다.gemini-embedding-001
의 경우 각 요청에는 단일 입력 텍스트만 포함될 수 있습니다. 자세한 내용은 텍스트 임베딩 한도를 참조하세요. - AUTO_TRUNCATE:
false
로 설정하면 토큰 한도를 초과하는 텍스트로 인해 요청이 실패합니다. 기본값은true
입니다.
HTTP 메서드 및 URL:
POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-embedding-001: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/gemini-embedding-001: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/gemini-embedding-001:predict" | Select-Object -Expand Content
다음과 비슷한 JSON 응답이 수신됩니다. values
는 공간 절약을 위해 잘렸습니다.
- 응답이 완전히 생성된 후 반환되도록 요청하려면
generateContent
메서드를 사용합니다. 시청자가 지연 시간에 대해 갖는 느낌을 줄이려면streamGenerateContent
메서드를 사용하여 생성되는 응답을 스트리밍합니다. - 멀티모달 모델 ID는 메서드 앞의 URL 끝 부분에 있습니다(예:
gemini-2.0-flash
). 이 샘플은 다른 모델도 지원할 수 있습니다.
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에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
지원되는 텍스트 언어
모든 텍스트 임베딩 모델은 영어 텍스트를 지원하며 이 텍스트를 기반으로 평가되었습니다. 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
.
gemini-embedding-001
모델은 다음 언어를 지원합니다.
Arabic
, Bengali
, Bulgarian
, Chinese (Simplified and Traditional)
, Croatian
, Czech
, Danish
, Dutch
, English
, Estonian
, Finnish
, French
, German
, Greek
, Hebrew
, Hindi
, Hungarian
, Indonesian
, Italian
, Japanese
, Korean
, Latvian
, Lithuanian
, Norwegian
, Polish
, Portuguese
, Romanian
, Russian
, Serbian
, Slovak
, Slovenian
, Spanish
, Swahili
, Swedish
, Thai
, Turkish
, Ukrainian
, Vietnamese
, Afrikaans
, Amharic
, Assamese
, Azerbaijani
, Belarusian
, Bosnian
, Catalan
, Cebuano
, Corsican
, Welsh
, Dhivehi
, Esperanto
, Basque
, Persian
, Filipino (Tagalog)
, Frisian
, Irish
, Scots Gaelic
, Galician
, Gujarati
, Hausa
, Hawaiian
, Hmong
, Haitian Creole
, Armenian
, Igbo
, Icelandic
, Javanese
, Georgian
, Kazakh
, Khmer
, Kannada
, Krio
, Kurdish
, Kyrgyz
, Latin
, Luxembourgish
, Lao
, Malagasy
, Maori
, Macedonian
, Malayalam
, Mongolian
, Meiteilon (Manipuri)
, Marathi
, Malay
, Maltese
, Myanmar (Burmese)
, Nepali
, Nyanja (Chichewa)
, Odia (Oriya)
, Punjabi
, Pashto
, Sindhi
, Sinhala (Sinhalese)
, Samoan
, Shona
, Somali
, Albanian
, Sesotho
, Sundanese
, Tamil
, Telugu
, Tajik
, Uyghur
, Urdu
, Uzbek
, Xhosa
, Yiddish
, Yoruba
, Zulu
.
모델 버전
현재 안정화 모델을 사용하려면 모델 버전 번호를 지정합니다(예: gemini-embedding-001
). 버전 번호 없이 모델을 지정하는 방식은 단순히 다른 모델에 대한 레거시 포인터이고 안정적이지 않으므로 권장되지 않습니다.
자세한 내용은 모델 버전 및 수명 주기를 참조하세요.
다음 단계
자세한 문서는 다음을 참조하세요.