Panduan ini menunjukkan cara menggunakan Text Embeddings API untuk mengonversi teks menjadi vektor numerik. Dokumen ini membahas topik berikut:
- Sintaksis: Panggil API menggunakan cURL atau Python SDK.
- Permintaan dan respons: Pelajari parameter permintaan dan respons untuk model embedding teks.
- Contoh: Lihat contoh kode yang menunjukkan cara menyematkan string teks.
- Langkah selanjutnya: Pelajari dokumentasi terkait.
API Text embeddings mengonversi teks menjadi vektor numerik yang disebut embedding. Representasi vektor ini menangkap makna semantik dan konteks teks.
Model yang Didukung:
Anda bisa mendapatkan embedding teks dengan menggunakan model berikut:
Nama model | Deskripsi | Dimensi Output | Panjang urutan maksimum | Bahasa teks yang didukung |
---|---|---|---|---|
gemini-embedding-001 |
Performa canggih untuk tugas bahasa Inggris, multibahasa, dan kode. Model ini menyatukan model khusus sebelumnya seperti text-embedding-005 dan text-multilingual-embedding-002 serta mencapai performa yang lebih baik di domain masing-masing. Baca Laporan Teknis kami untuk mengetahui detail selengkapnya. |
hingga 3072 | 2048 token | Bahasa teks yang didukung |
text-embedding-005 |
Khusus dalam tugas bahasa Inggris dan kode. | hingga 768 | 2048 token | Inggris |
text-multilingual-embedding-002 |
Khusus dalam tugas multibahasa. | hingga 768 | 2048 token | Bahasa teks yang didukung |
Untuk kualitas embedding yang lebih baik, gemini-embedding-001
adalah model besar kami yang dirancang untuk memberikan performa tertinggi. Perhatikan bahwa
gemini-embedding-001
mendukung satu instance per permintaan.
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(...)
Permintaan dan respons
Isi permintaan
{
"instances": [
{
"task_type": "RETRIEVAL_DOCUMENT",
"title": "document title",
"content": "I would like embeddings for this text!"
},
]
}
Parameter permintaan
instances
: Wajib diisi. Daftar objek yang berisi teks yang akan disematkan. Kolom berikut didukung:content
(string
): Teks yang akan dibuatkan embedding-nya.task_type
(string
): Opsional. Menentukan aplikasi downstream yang dimaksudkan untuk membantu model menghasilkan embedding dengan kualitas yang lebih baik. Jika Anda tidak menentukan nilai, defaultnya adalahRETRIEVAL_QUERY
. Untuk mengetahui informasi selengkapnya tentang jenis tugas, lihat Memilih jenis tugas embedding.title
(string
): Opsional. Judul untuk konten teks. Kolom ini hanya berlaku jikatask_type
adalahRETRIEVAL_DOCUMENT
.
parameters
: Opsional. Objek yang berisi kolom berikut:autoTruncate
(bool
): Jikatrue
, teks input dipangkas jika lebih panjang dari panjang maksimum model. Jikafalse
, error akan ditampilkan untuk input yang terlalu besar. Defaultnya adalahtrue
.outputDimensionality
(int
): Ukuran embedding yang diinginkan. Jika disetel, sematan output akan dipangkas ke dimensi ini.
Jenis tugas
Tabel berikut menjelaskan nilai parameter task_type
dan kasus penggunaannya:
task_type |
Deskripsi | Kasus Penggunaan |
---|---|---|
RETRIEVAL_QUERY |
Teks input adalah kueri dalam setelan penelusuran atau pengambilan. | Gunakan untuk teks kueri saat menelusuri koleksi dokumen. Pasangkan dengan RETRIEVAL_DOCUMENT untuk dokumen. |
RETRIEVAL_DOCUMENT |
Teks input adalah dokumen dalam setelan penelusuran atau pengambilan. | Gunakan untuk dokumen dalam koleksi yang akan ditelusuri. Pasangkan dengan RETRIEVAL_QUERY untuk kueri penelusuran. |
SEMANTIC_SIMILARITY |
Teks input digunakan untuk Kemiripan Teks Semantik (STS). | Membandingkan dua bagian teks untuk menentukan kesamaan maknanya. |
CLASSIFICATION |
Embedding akan digunakan untuk tugas klasifikasi. | Melatih model untuk mengategorikan teks ke dalam kelas yang telah ditentukan. |
CLUSTERING |
Embedding akan digunakan untuk tugas pengelompokan. | Mengelompokkan teks serupa tanpa label yang telah ditentukan sebelumnya. |
QUESTION_ANSWERING |
Teks input adalah kueri untuk sistem tanya jawab. | Menemukan jawaban atas pertanyaan dalam sekumpulan dokumen. Gunakan RETRIEVAL_DOCUMENT untuk dokumen. |
FACT_VERIFICATION |
Teks input adalah klaim yang akan diverifikasi terhadap sekumpulan dokumen. | Memverifikasi akurasi faktual suatu pernyataan. Gunakan RETRIEVAL_DOCUMENT untuk dokumen. |
CODE_RETRIEVAL_QUERY |
Teks input adalah kueri untuk mengambil cuplikan kode yang relevan (Java dan Python). | Menelusuri codebase untuk menemukan fungsi atau cuplikan yang relevan. Gunakan RETRIEVAL_DOCUMENT untuk dokumen kode. |
- Tugas pengambilan:
- Kueri: Gunakan
task_type=RETRIEVAL_QUERY
untuk teks input yang merupakan kueri penelusuran. - Korpus: Gunakan
task_type=RETRIEVAL_DOCUMENT
untuk teks input yang merupakan bagian dari koleksi dokumen yang sedang ditelusuri.
- Kueri: Gunakan
- Tugas kesamaan:
- Kemiripan semantik: Gunakan
task_type=SEMANTIC_SIMILARITY
untuk kedua teks input guna menilai keseluruhan kemiripan maknanya.
- Kemiripan semantik: Gunakan
- Catatan:
SEMANTIC_SIMILARITY
tidak ditujukan untuk kasus penggunaan pengambilan seperti penelusuran dokumen dan pengambilan informasi. Untuk kasus penggunaan ini, gunakanRETRIEVAL_DOCUMENT
,RETRIEVAL_QUERY
,QUESTION_ANSWERING
, danFACT_VERIFICATION
.
Isi respons
{
"predictions": [
{
"embeddings": {
"statistics": {
"truncated": boolean,
"token_count": integer
},
"values": [ number ]
}
}
]
}
Parameter respons
predictions
: Daftar objek, dengan setiap objek sesuai dengan instance input dari permintaan. Setiap objek berisi kolom berikut:embeddings
: Embedding yang dihasilkan dari teks input. Isinya adalah kolom berikut:values
: Daftar float yang merepresentasikan vektor embedding teks input.statistics
: Statistik yang dihitung dari teks input. Isinya adalah kolom berikut:truncated
(bool
):true
jika teks input dipangkas karena lebih panjang dari jumlah maksimum token yang diizinkan oleh model.token_count
(int
): Jumlah token dalam teks input.
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
Contoh berikut menunjukkan cara mendapatkan embedding untuk string teks.
REST
Setelah Anda menyiapkan lingkungan, Anda dapat menggunakan REST untuk menguji perintah teks. Contoh berikut mengirim 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 dengan maksimal 2.048 token per teks untuk semua model kecuali
textembedding-gecko@001
. Panjang token input maksimum untuktextembedding-gecko@001
adalah 3072. Untukgemini-embedding-001
, setiap permintaan hanya dapat menyertakan satu teks input. Untuk mengetahui informasi selengkapnya, lihat Batas embedding teks. - 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/gemini-embedding-001: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/gemini-embedding-001: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/gemini-embedding-001: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 agar respons ditampilkan setelah dibuat sepenuhnya. Untuk mengurangi persepsi latensi bagi audiens manusia, streaming respons saat respons dibuat menggunakan metodestreamGenerateContent
. - ID model multimodal terletak di akhir URL sebelum metode
(misalnya,
gemini-2.0-flash
). Contoh ini mungkin mendukung model lain juga.
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 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 embedding teks mendukung teks berbahasa Inggris dan telah dievaluasi berdasarkan teks tersebut.
Model text-multilingual-embedding-002
juga mendukung bahasa berikut. Model ini telah dievaluasi dalam bahasa yang ada di daftar Bahasa yang dievaluasi.
- 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
.
Model gemini-embedding-001
mendukung bahasa berikut:
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
.
Versi model
Untuk menggunakan model stabil saat ini, tentukan nomor versi model, misalnya gemini-embedding-001
.
Menentukan model tanpa nomor versi tidak direkomendasikan karena merupakan pointer lama ke model lain dan tidak stabil.
Untuk mengetahui informasi selengkapnya, baca Versi dan siklus proses model.
Langkah berikutnya
Pelajari lebih lanjut embedding teks: