שיפור האיכות של חיפוש ו-RAG באמצעות API לדירוג

כחלק מחוויית השימוש ב-Retrieval-Augmented Generation (יצירה משולבת-אחזור, RAG) ב-Agent Search, אתם יכולים לדרג קבוצת מסמכים על סמך שאילתה.

‫Ranking API מקבל רשימה של מסמכים ומדרג אותם מחדש לפי מידת הרלוונטיות שלהם לשאילתה. בהשוואה להטמעות, שבוחנות רק את הדמיון הסמנטי של מסמך ושאילתה, ה-API לדירוג יכול לתת לכם ציונים מדויקים לגבי מידת ההתאמה של מסמך לשאילתה נתונה. אפשר להשתמש ב-ranking API כדי לשפר את האיכות של תוצאות החיפוש אחרי אחזור של קבוצה ראשונית של מסמכים מועמדים.

ה-API לדירוג הוא ללא שמירת מצב (stateless), ולכן אין צורך להוסיף מסמכים לאינדקס לפני ששולחים קריאה ל-API. כל מה שצריך לעשות הוא להעביר את השאילתה והמסמכים. לכן ה-API מתאים מאוד לדירוג מחדש של מסמכים מ-Vector Search ומפתרונות חיפוש אחרים.

בדף הזה מוסבר איך להשתמש ב-Ranking API כדי לדרג קבוצה של מסמכים על סמך שאילתה.

תרחישים לדוגמה

המטרה העיקרית של ה-API לדירוג היא לשפר את האיכות של תוצאות החיפוש.

עם זאת, ה-API לדירוג יכול להיות שימושי בכל תרחיש שבו צריך למצוא אילו קטעי תוכן הכי רלוונטיים לשאילתה של המשתמש. לדוגמה, ה-API לדירוג יכול לעזור לכם:

• איך למצוא את התוכן המתאים להזנה ב-LLM לצורך עיגון

• שיפור הרלוונטיות של חוויית חיפוש קיימת

• זיהוי קטעים רלוונטיים במסמך

התהליך הבא מתאר איך אפשר להשתמש ב-API לדירוג כדי לשפר את איכות התוצאות של מסמכים מחולקים:

1. משתמשים ב-Document AI Layout Parser API כדי לפצל קבוצת מסמכים לחלקים.

2. משתמשים ב-API להטמעות כדי ליצור הטמעות לכל אחד מהקטעים.

3. טוענים את ההטמעות לחיפוש וקטורי או לפתרון חיפוש אחר.

4. שליחת שאילתה לאינדקס החיפוש ואחזור של החלקים הכי רלוונטיים.

5. מדרגים מחדש את הקטעים הרלוונטיים באמצעות ה-API לדירוג.

נתוני קלט

מונח מרכזי: ב-API לדירוג, המונח רשומה מציין מסמך. רשומה מורכבת ממזהה, כותרת ותוכן של מסמך. בניגוד למסמכים שכלולים במאגרי הנתונים של Agent Search, הרשומות שמזינים ל-API לדירוג הן בפורמט JSON ולא נוספו לאינדקס על ידי Agent Search.

כדי להשתמש ב-API לדירוג, צריך להזין את הפרטים הבאים:

• השאילתה שלפיה אתם מדרגים את הרשומות.

  לדוגמה:

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

• קבוצת רשומות שרלוונטיות לשאילתה. הרשומות מוצגות כמערך של אובייקטים. כל רשומה יכולה לכלול מזהה ייחודי, כותרת ואת תוכן המסמך. לכל רשומה צריך לכלול כותרת, תוכן או את שניהם. מספר האסימונים המקסימלי שנתמך לכל רשומה תלוי בגרסת המודל שבה משתמשים. לדוגמה, מודלים עד גרסה 003 תומכים ב-512 אסימונים, וגרסה 004 תומכת ב-1,024 אסימונים. אם האורך המשולב של הכותרת והתוכן חורג ממגבלת הטוקנים של המודל, התוכן הנוסף מחולק למקטעים ומעובד בחלקים. אם רשומה נחשבת ארוכה מדי, חלק מהתוכן נחתך והמערכת מתעלמת ממנו.

  אפשר לכלול עד 1,000 רשומות בכל בקשה.

  לדוגמה, מערך רשומות נראה בערך כך: בפועל, המערך יכלול הרבה יותר רשומות והתוכן יהיה ארוך יותר:

  "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."
     }
  ]
  

• אופציונלי: המספר המקסימלי של רשומות שרוצים ש-API הדירוג יחזיר. כברירת מחדל, כל הרשומות מוחזרות, אבל אפשר להשתמש בשדה topN כדי להחזיר פחות רשומות. כל הרשומות מדורגות, לא משנה מה הערך שמוגדר.

  לדוגמה, השאילתה הבאה מחזירה את 10 הרשומות המובילות:

  "topN": 10,
  

• אופציונלי: הגדרה שקובעת אם אתם רוצים שה-API יחזיר רק את המזהה של הרשומה, או גם את הכותרת והתוכן של הרשומה. כברירת מחדל, מוחזרת הרשומה המלאה. הסיבה העיקרית להגדרת השדה הזה היא אם רוצים להקטין את הגודל של המטען הייעודי (payload) של התגובה.

  לדוגמה, אם מגדירים את הערך true, מוחזר רק מזהה הרשומה, ולא הכותרת או התוכן:

  "ignoreRecordDetailsInResponse": true,
  

• אופציונלי: שם המודל. ההגדרה הזו מציינת את המודל שבו צריך להשתמש כדי לדרג את המסמכים. אם לא מציינים מודל, המערכת משתמשת ב-semantic-ranker-default@latest, שמפנה אוטומטית למודל הזמין האחרון. כדי להפנות למודל ספציפי, מציינים את אחד משמות המודלים שמפורטים בקטע מודלים נתמכים, לדוגמה semantic-ranker-512-003.

  בדוגמה הבאה, הערך של model מוגדר ל-semantic-ranker-default@latest. המשמעות היא שה-API לדירוג תמיד ישתמש במודל הזמין העדכני ביותר.

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

נתוני פלט

ה-API של הדירוג מחזיר רשימה מדורגת של רשומות עם הפלטים הבאים:

• ציון: ערך עשרוני בין 0 ל-1 שמציין את הרלוונטיות של הרשומה.

• מזהה: המזהה הייחודי של הרשומה.

• אם נדרש, האובייקט המלא: המזהה, הכותרת והתוכן.

  לדוגמה:

{
    "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."
        }
    ]
}

דירוג (או דירוג מחדש) של קבוצת רשומות לפי שאילתה

בדרך כלל, מספקים ל-API לדירוג שאילתה וקבוצת רשומות שרלוונטיות לשאילתה הזו, וכבר דורגו בשיטה אחרת, כמו חיפוש לפי מילות מפתח או חיפוש וקטורי. לאחר מכן, אתם משתמשים ב-API לדירוג כדי לשפר את איכות הדירוג ולקבוע ניקוד שמציין את הרלוונטיות של כל רשומה לשאילתה.

1. משיגים את השאילתה ואת הרשומות שמתקבלות. חשוב לוודא שלכל רשומה יש מזהה, וגם כותרת, תוכן או שניהם.

   מספר האסימונים המקסימלי שנתמך בכל רשומה תלוי בגרסת המודל. מודלים עד גרסה 003, כמו semantic-ranker-512-003, תומכים ב-512 אסימונים לכל רשומה. החל מגרסה 004, המגבלה הזו גדלה ל-1,024 אסימונים. אם האורך המשולב של הכותרת והתוכן חורג ממגבלת הטוקנים של המודל, התוכן הנוסף מחולק לחלקים ומעובד במקטעים. במקרים קיצוניים, אם רשומה נחשבת ארוכה מדי, חלק מהתוכן ייחתך והמערכת תתעלם ממנו.

2. מבצעים קריאה ל-rankingConfigs.rank באמצעות הקוד הבא:

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"
    }
]
}'

מחליפים את מה שכתוב בשדות הבאים:

• ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
• ‫QUERY: השאילתה שלפיה הרשומות מדורגות ומקבלות ניקוד.
• ‫RECORD_ID_n: מחרוזת ייחודית שמזהה את הרשומה.
• ‫TITLE_n: שם הרשומה.
• ‫CONTENT_n: תוכן הרשומה.

הערה: כדי לבדוק את ה-API, אתם יכולים להקליד ערכים משלכם בפלייסהולדרים האלה ולהדביק את הפקודה ב-Cloud Shell. אבל בפועל, המערך records יהיה גדול יותר.

מידע כללי על השיטה הזו זמין במאמר rankingConfigs.rank.

כדי לראות דוגמה לפקודת 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

מידע נוסף מופיע במאמרי העזרה של Agent Search Python API.

כדי לבצע אימות ב-"חיפוש מבוסס סוכנים", צריך להגדיר את Application Default Credentials. למידע נוסף, ראו הגדרת אימות לסביבת פיתוח מקומית.

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)

כדי לראות דוגמה ל-Ranking API, הריצו את ה-notebook‏ "Ranking API Beir evaluation" באחת מהסביבות הבאות:

פתיחה ב-Colab | הצגה ב-GitHub

מודלים נתמכים

אלה המודלים שזמינים:

שם הדגם	המודל האחרון שמוגדר כברירת מחדל (semantic-ranker-default@latest)	המודל המהיר העדכני (semantic-ranker-fast@latest)	קלט	חלון ההקשר	תאריך השקה	תאריך הפסקת השירות
semantic-ranker-default-005	כן	לא	טקסט (25 שפות)	1024	‫1 בספטמבר 2026	עדיין לא נקבע
semantic-ranker-fast-005	לא	כן	טקסט (25 שפות)	1024	‫1 בספטמבר 2026	עדיין לא נקבע
semantic-ranker-default-004	לא	לא	טקסט (25 שפות)	1024	‫9 באפריל 2025	עדיין לא נקבע
semantic-ranker-fast-004	לא	לא	טקסט (25 שפות)	1024	‫9 באפריל 2025	עדיין לא נקבע
semantic-ranker-default-003	לא	לא	טקסט (25 שפות)	512	‫10 בספטמבר 2024	עדיין לא נקבע
semantic-ranker-default-002	לא	לא	טקסט (באנגלית בלבד)	512	‫3 ביוני 2024	עדיין לא נקבע

המאמרים הבאים

איך משתמשים ב-method לדירוג עם ממשקי API אחרים של RAG כדי ליצור תשובות מבוססות-קרקע מנתונים לא מובְנים