Meningkatkan kualitas penelusuran dan RAG dengan API peringkat

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

API peringkat mengambil daftar dokumen dan memberi peringkat ulang pada 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 akurat untuk seberapa baik dokumen menjawab kueri tertentu. API peringkat dapat digunakan untuk meningkatkan kualitas hasil penelusuran setelah mengambil kumpulan awal dokumen kandidat.

API peringkat tidak memiliki status sehingga Anda tidak perlu mengindeks dokumen sebelum memanggil API. Yang perlu Anda lakukan adalah meneruskan kueri dan dokumen. Hal ini membuat API cocok untuk memberi peringkat ulang dokumen dari Vector Search dan solusi penelusuran lainnya.

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

Kasus penggunaan

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

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

  • Menemukan konten yang tepat untuk diberikan kepada LLM untuk grounding

  • Meningkatkan relevansi pengalaman penelusuran yang ada

  • Mengidentifikasi bagian dokumen yang relevan

Alur berikut menguraikan cara Anda dapat menggunakan API peringkat untuk meningkatkan kualitas hasil dokumen yang dibagi menjadi beberapa bagian:

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

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

  3. Muat embedding ke Vector Search atau solusi penelusuran lainnya.

  4. Kueri indeks penelusuran Anda dan ambil bagian yang paling relevan.

  5. Beri peringkat ulang bagian yang relevan menggunakan API peringkat.

Data input

API peringkat memerlukan input berikut:

  • Kueri yang digunakan untuk memberi peringkat pada catatan.

    Contoh:

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

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

    Misalnya, array catatan terlihat seperti ini. Pada kenyataannya, lebih banyak catatan akan 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 catatan yang Anda inginkan untuk ditampilkan oleh API peringkat. Secara default, semua catatan akan ditampilkan; namun, Anda dapat menggunakan kolom topN untuk menampilkan lebih sedikit catatan. Semua catatan diberi peringkat, terlepas dari nilai yang ditetapkan.

    Misalnya, kode ini menampilkan 10 catatan teratas yang diberi peringkat:

    "topN": 10,

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

    Misalnya, menetapkan ke true hanya akan menampilkan ID catatan, bukan judul atau konten:

    "ignoreRecordDetailsInResponse": true,

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

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

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

Data output

API peringkat menampilkan daftar catatan yang diberi peringkat dengan output berikut:

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

  • ID: ID unik catatan.

  • 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) pada sekumpulan catatan sesuai dengan kueri

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

  1. Dapatkan kueri dan catatan hasil. Pastikan setiap catatan memiliki ID dan judul, konten, atau keduanya.

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

  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 Anda. Google Cloud
  • QUERY: kueri yang digunakan untuk memberi peringkat dan skor pada catatan.
  • RECORD_ID_n: string unik yang mengidentifikasi catatan.
  • TITLE_n: judul catatan.
  • CONTENT_n: konten catatan.

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 Penelusuran Agen Python API dokumentasi referensi.

Untuk melakukan autentikasi ke Penelusuran Agen, 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)

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-004 Ya Tidak Teks (25 bahasa) 1024 9 April 2025 Belum ditentukan
semantic-ranker-fast-004 Tidak Ya 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 (hanya bahasa Inggris) 512 3 Juni 2024 Belum ditentukan

Langkah berikutnya

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