Text embeddings API mengonversi data tekstual menjadi vektor numerik. Representasi vektor ini dirancang untuk menangkap makna dan konteks semantik dari kata-kata yang direpresentasikannya.
Model yang Didukung:
Model bahasa Inggris | Model multibahasa | Model penyematan Gemini |
---|---|---|
text-embedding-005 |
text-multilingual-embedding-002 |
gemini-embedding-001 |
Sintaks
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(...)
Daftar parameter
Kolom tingkat teratas | |
---|---|
|
Daftar objek yang berisi kolom berikut:
|
|
Objek yang berisi kolom berikut:
|
instance kolom |
|
---|---|
|
Teks yang ingin Anda buatkan embedding-nya. |
|
Opsional: Digunakan untuk menyampaikan aplikasi downstream yang dimaksudkan untuk membantu model menghasilkan penyematan yang lebih baik. Jika dibiarkan kosong, default yang digunakan adalah
Untuk informasi selengkapnya tentang jenis tugas, lihat Memilih jenis tugas penyematan. |
|
Opsional: Digunakan untuk membantu model menghasilkan penyematan yang lebih baik.
Hanya berlaku jika digunakan bersama |
task_type
Tabel berikut menjelaskan nilai parameter task_type
dan kasus
penggunaannya:
task_type |
Deskripsi |
---|---|
RETRIEVAL_QUERY |
Menentukan bahwa teks yang diberikan merupakan kueri dalam setelan penelusuran atau pengambilan. Gunakan RETRIEVAL_DOCUMENT untuk sisi dokumen. |
RETRIEVAL_DOCUMENT |
Menentukan bahwa teks yang diberikan adalah dokumen dalam setelan penelusuran atau pengambilan. |
SEMANTIC_SIMILARITY |
Menentukan bahwa teks yang diberikan digunakan untuk Kemiripan Teks Semantik (STS). |
CLASSIFICATION |
Menentukan bahwa penyematan digunakan untuk klasifikasi. |
CLUSTERING |
Menentukan bahwa penyematan digunakan untuk pengelompokan. |
QUESTION_ANSWERING |
Menentukan bahwa penyematan kueri digunakan untuk menjawab pertanyaan. Gunakan RETRIEVAL_DOCUMENT untuk sisi dokumen. |
FACT_VERIFICATION |
Menentukan bahwa penyematan kueri digunakan untuk verifikasi fakta. Gunakan RETRIEVAL_DOCUMENT untuk sisi dokumen. |
CODE_RETRIEVAL_QUERY |
Menentukan bahwa penyematan kueri digunakan untuk pengambilan kode untuk Java dan Python. Gunakan RETRIEVAL_DOCUMENT untuk sisi dokumen. |
Tugas Pengambilan:
Kueri: Gunakan task_type=RETRIEVAL_QUERY
untuk menunjukkan bahwa teks input adalah kueri penelusuran.
Korpus: Gunakan task_type=RETRIEVAL_DOCUMENT
untuk menunjukkan bahwa teks input adalah bagian
dari koleksi dokumen yang ditelusuri.
Tugas Kesamaan:
Kesamaan semantik: Gunakan task_type= SEMANTIC_SIMILARITY
untuk kedua teks input guna menilai kesamaan makna secara keseluruhan.
parameters kolom |
|
---|---|
|
Opsional: Jika disetel ke true, teks input akan terpotong. Jika disetel ke salah (false), error akan ditampilkan jika teks input lebih panjang dari panjang maksimum yang didukung oleh model. Nilai defaultnya adalah true (benar). |
|
Opsional: Digunakan untuk menentukan ukuran penyematan output. Jika ditetapkan, penyematan output akan terpotong ke ukuran yang ditentukan. |
Isi permintaan
{
"instances": [
{
"task_type": "RETRIEVAL_DOCUMENT",
"title": "document title",
"content": "I would like embeddings for this text!"
},
]
}
Isi respons
{
"predictions": [
{
"embeddings": {
"statistics": {
"truncated": boolean,
"token_count": integer
},
"values": [ number ]
}
}
]
}
Elemen respons | |
---|---|
|
Daftar objek dengan kolom berikut:
|
embeddings kolom |
|
---|---|
|
Daftar |
|
Statistik yang dihitung dari teks input. Berisi:
|
Contoh respons
{
"predictions": [
{
"embeddings": {
"values": [
0.0058424929156899452,
0.011848051100969315,
0.032247550785541534,
-0.031829461455345154,
-0.055369812995195389,
...
],
"statistics": {
"token_count": 4,
"truncated": false
}
}
}
]
}
Contoh
Menyematkan string teks
Kasus penggunaan dasar
Contoh berikut menunjukkan cara mendapatkan penyematan string teks.
REST
Setelah menyiapkan lingkungan, Anda dapat menggunakan REST untuk menguji perintah teks. Contoh berikut mengirimkan permintaan ke endpoint model penayang.
Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:
- PROJECT_ID: Project ID Anda.
- TEXT: Teks yang ingin Anda buatkan embedding-nya. Batas: lima teks hingga 2.048 token per teks untuk semua model kecuali
textembedding-gecko@001
. Panjang token input maksimum untuktextembedding-gecko@001
adalah 3072. - AUTO_TRUNCATE: Jika ditetapkan ke
false
, teks yang melebihi batas token akan menyebabkan permintaan gagal. Nilai defaultnya adalahtrue
.
Metode HTTP dan URL:
POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/text-embedding-005:predict
Isi JSON permintaan:
{ "instances": [ { "content": "TEXT"} ], "parameters": { "autoTruncate": AUTO_TRUNCATE } }
Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:
curl
Simpan isi permintaan dalam file bernama request.json
,
dan jalankan perintah berikut:
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-005:predict"
PowerShell
Simpan isi permintaan dalam file bernama request.json
,
dan jalankan perintah berikut:
$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-005:predict" | Select-Object -Expand Content
Anda akan menerima respons JSON yang mirip dengan yang berikut ini: Perhatikan bahwa values
telah dipotong untuk menghemat ruang penyimpanan.
- Gunakan metode
generateContent
untuk meminta respons ditampilkan setelah sepenuhnya dibuat. Untuk mengurangi persepsi latensi kepada audiens manusia, streaming respons saat dihasilkan menggunakan metodestreamGenerateContent
. - ID model multimodal terletak di akhir URL sebelum metode
(misalnya,
gemini-2.0-flash
). Contoh ini mungkin juga mendukung model lainnya.
Vertex AI SDK untuk Python
Untuk mempelajari cara menginstal atau mengupdate Vertex AI SDK untuk Python, lihat Menginstal Vertex AI SDK untuk Python. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Vertex AI SDK untuk Python.
Go
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Go di Panduan memulai Vertex AI menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Go Vertex AI.
Untuk melakukan autentikasi ke Vertex AI, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Java
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di Panduan memulai Vertex AI menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Java Vertex AI.
Untuk melakukan autentikasi ke Vertex AI, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Node.js
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Node.js di Panduan memulai Vertex AI menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Node.js Vertex AI.
Untuk melakukan autentikasi ke Vertex AI, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Kasus Penggunaan Lanjutan
Contoh berikut menunjukkan beberapa fitur lanjutan
- Gunakan
task_type
dantitle
untuk meningkatkan kualitas penyematan. - Gunakan parameter untuk mengontrol perilaku API.
REST
Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:
- PROJECT_ID: Project ID Anda.
- TEXT: Teks yang ingin Anda buatkan embedding-nya. Batas: lima teks hingga 3.072 token per teks.
- TASK_TYPE: Digunakan untuk menyampaikan aplikasi downstream yang dimaksudkan untuk membantu model menghasilkan penyematan yang lebih baik.
- TITLE: Digunakan untuk membantu model menghasilkan embedding yang lebih baik.
- AUTO_TRUNCATE: Jika ditetapkan ke
false
, teks yang melebihi batas token akan menyebabkan permintaan gagal. Nilai defaultnya adalahtrue
. - OUTPUT_DIMENSIONALITY: Digunakan untuk menentukan ukuran penyematan output. Jika ditetapkan, penyematan output akan terpotong ke ukuran yang ditentukan.
Metode HTTP dan URL:
POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/textembedding-gecko@003:predict
Isi JSON permintaan:
{ "instances": [ { "content": "TEXT", "task_type": "TASK_TYPE", "title": "TITLE" }, ], "parameters": { "autoTruncate": AUTO_TRUNCATE, "outputDimensionality": OUTPUT_DIMENSIONALITY } }
Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:
curl
Simpan isi permintaan dalam file bernama request.json
,
dan jalankan perintah berikut:
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
Simpan isi permintaan dalam file bernama request.json
,
dan jalankan perintah berikut:
$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
Anda akan menerima respons JSON yang mirip dengan yang berikut ini: Perhatikan bahwa values
telah dipotong untuk menghemat ruang penyimpanan.
Vertex AI SDK untuk Python
Untuk mempelajari cara menginstal atau mengupdate Vertex AI SDK untuk Python, lihat Menginstal Vertex AI SDK untuk Python. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Vertex AI SDK untuk Python.
Go
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Go di Panduan memulai Vertex AI menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Go Vertex AI.
Untuk melakukan autentikasi ke Vertex AI, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Java
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di Panduan memulai Vertex AI menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Java Vertex AI.
Untuk melakukan autentikasi ke Vertex AI, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Node.js
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Node.js di Panduan memulai Vertex AI menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi API Node.js Vertex AI.
Untuk melakukan autentikasi ke Vertex AI, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Bahasa teks yang didukung
Semua model penyematan teks mendukung dan telah dievaluasi pada teks
bahasa Inggris. Model textembedding-gecko-multilingual@001
dan
text-multilingual-embedding-002
juga mendukung dan telah
dievaluasi dalam bahasa berikut:
- Bahasa yang dievaluasi:
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)
- Bahasa yang didukung:
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
.
Versi model
Untuk menggunakan model stabil saat ini, tentukan nomor versi model, misalnya
text-embedding-005
. Menentukan model tanpa nomor versi,
seperti textembedding-gecko
, tidak direkomendasikan, karena hanya merupakan pointer
lama ke model lain dan tidak stabil.
Untuk mengetahui informasi selengkapnya, baca Versi dan siklus proses model.
Langkah berikutnya
Untuk dokumentasi mendetail, lihat hal berikut: