Meningkatkan kualitas penelusuran dan RAG dengan API peringkat

Sebagai bagian dari pengalaman Retrieval Augmented Generation (RAG) Anda di Agent Search, Anda dapat memberi peringkat pada sekumpulan dokumen berdasarkan kueri.

API peringkat mengambil daftar dokumen dan memberi peringkat ulang dokumen tersebut berdasarkan seberapa relevan dokumen tersebut dengan kueri. Dibandingkan dengan embedding, yang hanya melihat kemiripan semantik dokumen dan kueri, API peringkat dapat memberi Anda skor yang tepat untuk seberapa baik dokumen menjawab kueri tertentu. API peringkat dapat digunakan untuk meningkatkan kualitas hasil penelusuran setelah mengambil kumpulan awal dokumen kandidat.

Ranking API tidak memiliki status sehingga Anda tidak perlu mengindeks dokumen sebelum memanggil API. Anda hanya perlu meneruskan kueri dan dokumen. Hal ini membuat API sangat cocok untuk memberi peringkat ulang dokumen dari Penelusuran Vektor dan solusi penelusuran lainnya.

Halaman ini menjelaskan cara menggunakan API peringkat untuk memberi peringkat pada sekumpulan dokumen berdasarkan kueri.

Kasus penggunaan

Kasus penggunaan utama ranking API adalah untuk meningkatkan kualitas hasil penelusuran.

Namun, API peringkat dapat berguna untuk skenario apa pun saat Anda perlu menemukan konten yang paling relevan dengan kueri pengguna. Misalnya, ranking API dapat membantu Anda dalam hal berikut:

• Menemukan konten yang tepat untuk diberikan ke LLM sebagai perujukan

• Meningkatkan relevansi pengalaman penelusuran yang ada

• Mengidentifikasi bagian dokumen yang relevan

Alur berikut menguraikan cara Anda dapat menggunakan API peringkat untuk meningkatkan kualitas hasil untuk dokumen yang di-chunk:

1. Gunakan Document AI Layout Parser API untuk membagi sekumpulan dokumen menjadi beberapa bagian.

2. Gunakan API embedding untuk membuat embedding untuk setiap potongan.

3. Memuat embedding ke dalam Vector Search atau solusi penelusuran lainnya.

4. Membuat kueri indeks penelusuran dan mengambil potongan yang paling relevan.

5. Memberi peringkat ulang pada potongan yang relevan menggunakan API peringkat.

Data input

Istilah Utama: Ranking API menggunakan istilah record untuk menunjukkan dokumen. Kumpulan data terdiri dari ID, judul, dan konten dokumen. Tidak seperti dokumen yang terdapat dalam penyimpanan data Agent Search, input data ke API peringkat dalam format JSON dan belum diindeks oleh Agent Search.

Ranking API memerlukan input berikut:

• Kueri yang datanya Anda beri peringkat.

  Contoh:

  "query": "Why is the sky blue?"
  

• Kumpulan data yang relevan dengan kueri. Data disediakan sebagai array objek. Setiap catatan dapat menyertakan ID unik, judul, dan konten dokumen. Untuk setiap catatan, sertakan judul, konten, atau keduanya. Jumlah maksimum token yang didukung per rekaman bergantung pada versi model yang digunakan. Misalnya, model hingga versi 003 mendukung 512 token, sedangkan versi 004 mendukung 1.024 token. Jika panjang gabungan judul dan konten melebihi batas token model, konten tambahan akan dipangkas. Anda dapat menyertakan hingga 1.000 data per permintaan.

  Misalnya, array data terlihat seperti ini. Pada kenyataannya, akan ada lebih banyak data yang disertakan dalam array dan kontennya akan jauh lebih panjang:

  "records": [
     {
         "id": "1",
         "title": "The Color of the Sky: A Poem",
         "content": "A canvas stretched across the day,\nWhere sunlight learns to dance and play.\nBlue, a hue of scattered light,\nA gentle whisper, soft and bright."
     },
     {
         "id": "2",
         "title": "The Science of a Blue Sky",
         "content": "The sky appears blue due to a phenomenon called Rayleigh scattering. Sunlight is comprised of all the colors of the rainbow. Blue light has shorter wavelengths than other colors, and is thus scattered more easily."
     }
  ]
  

• Opsional: Jumlah maksimum data yang Anda inginkan untuk ditampilkan oleh API peringkat. Secara default, semua data akan ditampilkan; namun, Anda dapat menggunakan kolom topN untuk menampilkan lebih sedikit data. Semua data diberi peringkat, terlepas dari nilai yang ditetapkan.

  Misalnya, ini akan menampilkan 10 kumpulan data teratas yang diberi peringkat:

  "topN": 10,
  

• Opsional: Setelan yang menentukan apakah Anda hanya menginginkan ID data yang ditampilkan oleh API atau apakah Anda juga ingin judul dan konten data ditampilkan. Secara default, data lengkap akan ditampilkan. Alasan utama untuk menyetel ini adalah jika Anda ingin mengurangi ukuran payload respons.

  Misalnya, menyetel ke true hanya akan menampilkan ID rekaman, bukan judul atau konten:

  "ignoreRecordDetailsInResponse": true,
  

• Opsional: Nama model. Ini menentukan model yang akan digunakan untuk memberi peringkat dokumen. Jika tidak ada model yang ditentukan, semantic-ranker-default@latest akan digunakan, yang otomatis mengarah ke model terbaru yang tersedia. Untuk mengarah ke model tertentu, tentukan salah satu nama model yang tercantum dalam Model yang didukung, misalnya semantic-ranker-512-003.

  Dalam contoh berikut, model ditetapkan ke semantic-ranker-default@latest. Artinya, Ranking API akan selalu menggunakan model terbaru yang tersedia.

  "model": "semantic-ranker-default@latest"
  

Data output

API peringkat menampilkan daftar peringkat data dengan output berikut:

• Skor: nilai float antara 0 dan 1 yang menunjukkan relevansi rekaman.

• ID: ID unik data.

• Jika diminta, objek lengkap: ID, judul, dan konten.

  Contoh:

{
    "records": [
        {
            "id": "2",
            "score": 0.98,
            "title": "The Science of a Blue Sky",
            "content": "The sky appears blue due to a phenomenon called Rayleigh scattering. Sunlight is comprised of all the colors of the rainbow. Blue light has shorter wavelengths than other colors, and is thus scattered more easily."
        },
        {
            "id": "1",
            "score": 0.64,
            "title": "The Color of the Sky: A Poem",
            "content": "A canvas stretched across the day,\nWhere sunlight learns to dance and play.\nBlue, a hue of scattered light,\nA gentle whisper, soft and bright."
        }
    ]
}

Memberi peringkat (atau memberi peringkat ulang) kumpulan data sesuai dengan kueri

Biasanya, Anda akan memberikan kueri dan sekumpulan data yang relevan dengan kueri tersebut dan telah diberi peringkat dengan metode lain seperti penelusuran kata kunci atau penelusuran vektor ke Ranking API. Kemudian, Anda menggunakan API peringkat untuk meningkatkan kualitas peringkat dan menentukan skor yang menunjukkan relevansi setiap data dengan kueri.

1. Mendapatkan kueri dan data yang dihasilkan. Pastikan setiap data memiliki ID dan judul, konten, atau keduanya.

   Jumlah maksimum token yang didukung per rekaman bergantung pada versi model. Model hingga versi 003, seperti semantic-ranker-512-003, mendukung 512 token per rekaman. Mulai versi 004, batas ini meningkat menjadi 1.024 token. Jika panjang gabungan judul dan konten melebihi batas token model, konten tambahan akan dipotong.

2. Panggil metode rankingConfigs.rank menggunakan kode berikut:

REST

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/rankingConfigs/default_ranking_config:rank" \
-d '{
"model": "semantic-ranker-default@latest",
"query": "QUERY",
"records": [
    {
        "id": "RECORD_ID_1",
        "title": "TITLE_1",
        "content": "CONTENT_1"
    },
    {
        "id": "RECORD_ID_2",
        "title": "TITLE_2",
        "content": "CONTENT_2"
    },
    {
        "id": "RECORD_ID_3",
        "title": "TITLE_3",
        "content": "CONTENT_3"
    }
]
}'

Ganti kode berikut:

• PROJECT_ID: ID project Google Cloud Anda.
• QUERY: kueri yang digunakan untuk memberi peringkat dan skor pada kumpulan data.
• RECORD_ID_n: string unik yang mengidentifikasi data.
• TITLE_n: judul rekaman.
• CONTENT_n: konten data.

Catatan: Anda dapat menguji API dengan mengetik nilai Anda sendiri ke dalam placeholder ini dan menempelkan perintah ke Cloud Shell. Namun, pada kenyataannya, array records akan lebih besar.

Untuk mengetahui informasi umum tentang metode ini, lihat rankingConfigs.rank.

Klik untuk melihat contoh perintah dan respons curl.

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: my-project-123" \
    "https://discoveryengine.googleapis.com/v1/projects/my-project-123/locations/global/rankingConfigs/default_ranking_config:rank" \
    -d '{
        "model": "semantic-ranker-default@latest",
        "query": "what is Google gemini?",
        "records": [
            {
                "id": "1",
                "title": "Gemini",
                "content": "The Gemini zodiac symbol often depicts two figures standing side-by-side."
            },
            {
                "id": "2",
                "title": "Gemini",
                "content": "Gemini is a cutting edge large language model created by Google."
            },
            {
                "id": "3",
                "title": "Gemini Constellation",
                "content": "Gemini is a constellation that can be seen in the night sky."
            }
        ]
    }'
    

{
    "records": [
        {
            "id": "2",
            "title": "Gemini",
            "content": "Gemini is a cutting edge large language model created by Google.",
            "score": 0.97
        },
        {
            "id": "3",
            "title": "Gemini Constellation",
            "content": "Gemini is a constellation that can be seen in the night sky.",
            "score": 0.18
        },
        {
            "id": "1",
            "title": "Gemini",
            "content": "The Gemini zodiac symbol often depicts two figures standing side-by-side.",
            "score": 0.05
        }
    ]
}

Python

Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API Python Agent Search.

Untuk melakukan autentikasi ke Agent Search, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

from google.cloud import discoveryengine_v1 as discoveryengine

# TODO(developer): Uncomment these variables before running the sample.
# project_id = "YOUR_PROJECT_ID"

client = discoveryengine.RankServiceClient()

# The full resource name of the ranking config.
# Format: projects/{project_id}/locations/{location}/rankingConfigs/default_ranking_config
ranking_config = client.ranking_config_path(
    project=project_id,
    location="global",
    ranking_config="default_ranking_config",
)
request = discoveryengine.RankRequest(
    ranking_config=ranking_config,
    model="semantic-ranker-default@latest",
    top_n=10,
    query="What is Google Gemini?",
    records=[
        discoveryengine.RankingRecord(
            id="1",
            title="Gemini",
            content="The Gemini zodiac symbol often depicts two figures standing side-by-side.",
        ),
        discoveryengine.RankingRecord(
            id="2",
            title="Gemini",
            content="Gemini is a cutting edge large language model created by Google.",
        ),
        discoveryengine.RankingRecord(
            id="3",
            title="Gemini Constellation",
            content="Gemini is a constellation that can be seen in the night sky.",
        ),
    ],
)

response = client.rank(request=request)

# Handle the response
print(response)

Untuk melihat contoh API peringkat, jalankan notebook "Evaluasi Beir API Peringkat" di salah satu lingkungan berikut:

Buka di Colab | Lihat di GitHub

Model yang didukung

Model berikut tersedia.

Nama model	Model default terbaru (semantic-ranker-default@latest)	Model cepat terbaru (semantic-ranker-fast@latest)	Input	Jendela konteks	Tanggal rilis	Tanggal penghentian
semantic-ranker-default-005	Ya	Tidak	Teks (25 bahasa)	1024	1 September 2026	Belum ditentukan
semantic-ranker-fast-005	Tidak	Ya	Teks (25 bahasa)	1024	1 September 2026	Belum ditentukan
semantic-ranker-default-004	Tidak	Tidak	Teks (25 bahasa)	1024	9 April 2025	Belum ditentukan
semantic-ranker-fast-004	Tidak	Tidak	Teks (25 bahasa)	1024	9 April 2025	Belum ditentukan
semantic-ranker-default-003	Tidak	Tidak	Teks (25 bahasa)	512	10 September 2024	Belum ditentukan
semantic-ranker-default-002	Tidak	Tidak	Teks (khusus bahasa Inggris)	512	3 Juni 2024	Belum ditentukan

Langkah berikutnya

Pelajari cara menggunakan metode peringkat dengan API RAG lainnya untuk menghasilkan jawaban yang didasarkan pada data tidak terstruktur.