File Search Stores

‫File Search API מספק שירות אירוח של מענה לשאלות לבניית מערכות Retrieval-Augmented Generation (יצירה משולבת-אחזור, RAG) באמצעות התשתית של Google.

משאב REST: ‏ fileSearchStores

משאב: FileSearchStore

FileSearchStore הוא אוסף של Document.

Fields
name string

פלט בלבד. אי אפשר לשנות. מזהה. FileSearchStore שם המשאב. זהו מזהה (שם ללא הקידומת fileSearchStores/) שיכול להכיל עד 40 תווים אלפאנומריים באותיות קטנות או מקפים (-). זהו שדה פלט בלבד. השם הייחודי יגזר מ-displayName יחד עם סיומת אקראית של 12 תווים. דוגמה: fileSearchStores/my-awesome-file-search-store-123a456b789c אם לא מציינים את displayName, השם ייווצר באופן אקראי.

displayName string

אופציונלי. השם המוצג של FileSearchStore שקריא לבני אדם. האורך של השם המוצג לא יכול להיות יותר מ-512 תווים, כולל רווחים. דוגמה: "Docs on Semantic Retriever"

createTime string (Timestamp format)

פלט בלבד. חותמת הזמן שבה נוצר FileSearchStore.

הפורמט הוא RFC 3339, והפלט שנוצר תמיד יהיה בפורמט Z עם 0, 3, 6 או 9 ספרות אחרי הנקודה. אפשר להשתמש גם בהיסטים אחרים, לא רק ב-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".

updateTime string (Timestamp format)

פלט בלבד. חותמת הזמן שבה FileSearchStore עודכן לאחרונה.

הפורמט הוא RFC 3339, והפלט שנוצר תמיד יהיה בפורמט Z עם 0, 3, 6 או 9 ספרות אחרי הנקודה. אפשר להשתמש גם בהיסטים אחרים, לא רק ב-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".

activeDocumentsCount string (int64 format)

פלט בלבד. מספר המסמכים בFileSearchStore שהם פעילים ומוכנים לאחזור.

pendingDocumentsCount string (int64 format)

פלט בלבד. מספר המסמכים ב-FileSearchStore שנמצאים בתהליך עיבוד.

failedDocumentsCount string (int64 format)

פלט בלבד. מספר המסמכים ב-FileSearchStore שהעיבוד שלהם נכשל.

sizeBytes string (int64 format)

פלט בלבד. הגודל של הבייטים הגולמיים שנקלטים ב-FileSearchStore. זהו הגודל הכולל של כל המסמכים ב-FileSearchStore.

embeddingModel string

אופציונלי. מודל ההטמעה שבו צריך להשתמש בשביל FileSearchStore. שם המשאב של המודל. השם הזה משמש כמזהה לשימוש במודל. פורמט: models/{model} אם לא מציינים מודל, המערכת תשתמש במודל ברירת המחדל להטמעה.

ייצוג ב-JSON 
{
  "name": string,
  "displayName": string,
  "createTime": string,
  "updateTime": string,
  "activeDocumentsCount": string,
  "pendingDocumentsCount": string,
  "failedDocumentsCount": string,
  "sizeBytes": string,
  "embeddingModel": string
}

שיטה: fileSearchStores.create

יוצרת FileSearchStore ריק.

נקודת קצה

post https://generativelanguage.googleapis.com/v1beta/fileSearchStores

גוף הבקשה

גוף הבקשה מכיל מופע של FileSearchStore.

Fields
displayName string

אופציונלי. השם המוצג של FileSearchStore שקריא לבני אדם. האורך של השם המוצג לא יכול להיות יותר מ-512 תווים, כולל רווחים. דוגמה: "Docs on Semantic Retriever"

embeddingModel string

אופציונלי. מודל ההטמעה שבו צריך להשתמש בשביל FileSearchStore. שם המשאב של המודל. השם הזה משמש כמזהה לשימוש במודל. פורמט: models/{model} אם לא מציינים מודל, המערכת תשתמש במודל ברירת המחדל להטמעה.

גוף התשובה

אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכיל מופע חדש של FileSearchStore.

שיטה: fileSearchStores.delete

מחיקת FileSearchStore.

נקודת קצה

delete https://generativelanguage.googleapis.com/v1beta/{name=fileSearchStores/*}

פרמטרים של נתיב

name string

חובה. שם המשאב של FileSearchStore. דוגמה: fileSearchStores/my-file-search-store-123 התוצאה תהיה fileSearchStores/{filesearchstore}.

פרמטרים של שאילתה

force boolean

אופציונלי. אם הערך מוגדר כ-true, גם כל ה-Document והאובייקטים שקשורים ל-FileSearchStore הזה יימחקו.

אם הערך הוא False (ברירת המחדל), תוחזר שגיאת FAILED_PRECONDITION אם FileSearchStore מכיל ערכים מסוג Document.

גוף הבקשה

גוף הבקשה צריך להיות ריק.

גוף התשובה

אם הפעולה בוצעה ללא שגיאות, גוף התגובה הוא אובייקט JSON ריק.

שיטה: fileSearchStores.get

קבלת מידע על FileSearchStore ספציפי.

נקודת קצה

get https://generativelanguage.googleapis.com/v1beta/{name=fileSearchStores/*}

פרמטרים של נתיב

name string

חובה. השם של FileSearchStore. דוגמה: fileSearchStores/my-file-search-store-123 התוצאה תהיה fileSearchStores/{filesearchstore}.

גוף הבקשה

גוף הבקשה צריך להיות ריק.

גוף התשובה

אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכיל מופע של FileSearchStore.

שיטה: fileSearchStores.list

רשימה של כל FileSearchStores שבבעלות המשתמש.

נקודת קצה

get https://generativelanguage.googleapis.com/v1beta/fileSearchStores

פרמטרים של שאילתה

pageSize integer

אופציונלי. המספר המקסימלי של FileSearchStores שיוחזרו (לכל דף). יכול להיות שהשירות יחזיר פחות מ-FileSearchStores.

אם לא מציינים ערך, יוחזרו לכל היותר 10 FileSearchStores. המגבלה המקסימלית היא 20 FileSearchStores לכל דף.

pageToken string

אופציונלי. טוקן של דף שהתקבל מקריאה קודמת של fileSearchStores.list.

כדי לאחזר את הדף הבא, צריך להזין את nextPageToken שמוחזר בתגובה כארגומנט לבקשה הבאה.

כשמבצעים חלוקה לעמודים, כל הפרמטרים האחרים שסופקו ל-fileSearchStores.list חייבים להיות זהים לקריאה שסיפקה את הטוקן של הדף.

גוף הבקשה

גוף הבקשה צריך להיות ריק.

גוף התשובה

תשובה מ-fileSearchStores.list שמכילה רשימה עם מספור דפים של FileSearchStores. התוצאות ממוינות לפי fileSearchStore.create_time בסדר עולה.

אם הפעולה מצליחה, גוף התגובה מכיל נתונים במבנה הבא:

Fields
fileSearchStores[] object (FileSearchStore)

החזרת rag_stores.

nextPageToken string

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

ייצוג ב-JSON 
{
  "fileSearchStores": [
    {
      object (FileSearchStore)
    }
  ],
  "nextPageToken": string
}

שיטה: fileSearchStores.importFile

ייבוא של File מ-File Service אל FileSearchStore.

נקודת קצה

post https://generativelanguage.googleapis.com/v1beta/{fileSearchStoreName=fileSearchStores/*}:importFile

פרמטרים של נתיב

fileSearchStoreName string

חובה. אי אפשר לשנות. השם של FileSearchStore שאליו רוצים לייבא את הקובץ. דוגמה: fileSearchStores/my-file-search-store-123 התוצאה תהיה fileSearchStores/{filesearchstore}.

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה הבא:

Fields
fileName string

חובה. השם של File לייבוא. לדוגמה: files/abc-123

customMetadata[] object (CustomMetadata)

מטא-נתונים בהתאמה אישית שרוצים לשייך לקובץ.

chunkingConfig object (ChunkingConfig)

אופציונלי. הגדרות שמציינות לשירות איך לחלק את הקובץ לחלקים. אם לא תציינו פרמטרים, השירות ישתמש בפרמטרים שמוגדרים כברירת מחדל.

גוף התשובה

אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכיל מופע של Operation.

משאב REST: ‏ fileSearchStores.operations

משאב: פעולה

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

Fields
name string

השם שהוקצה על ידי השרת, שהוא ייחודי רק בתוך אותו שירות שהחזיר אותו במקור. אם משתמשים במיפוי ברירת המחדל של HTTP, הערך של name צריך להיות שם משאב שמסתיים ב-operations/{unique_id}.

metadata object

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

אובייקט שמכיל שדות מסוג שרירותי. שדה נוסף "@type" מכיל URI שמזהה את הסוג. לדוגמה: { "id": 1234, "@type": "types.example.com/standard/id" }.

done boolean

אם הערך הוא false, המשמעות היא שהפעולה עדיין מתבצעת. אם הערך הוא true, הפעולה הושלמה ואפשר להשתמש בערך error או response.

result Union type
תוצאת הפעולה, שיכולה להיות error או response תקין. אם done == false, אף אחד מהערכים error או response לא מוגדר. אם done == true, אפשר להגדיר בדיוק אחד מהערכים error או response. יכול להיות שחלק מהשירותים לא יספקו את התוצאה. הרשימה הבאה כוללת שדות שאי אפשר להשתמש בהם בו-זמנית. בכל תשובה יוגדר לכל היותר אחד מהשדות:
error object (Status)

תוצאת השגיאה של הפעולה במקרה של כשל או ביטול.

response object

התגובה הרגילה והמוצלחת של הפעולה. אם השיטה המקורית לא מחזירה נתונים במקרה של הצלחה, כמו Delete, התגובה היא google.protobuf.Empty. אם ה-method המקורית היא סטנדרטית Get/Create/Update, התשובה צריכה להיות המשאב. בשיטות אחרות, התשובה צריכה להיות מהסוג XxxResponse, כאשר Xxx הוא שם השיטה המקורי. לדוגמה, אם שם השיטה המקורי הוא TakeSnapshot(), סוג התגובה שמוסק הוא TakeSnapshotResponse.

אובייקט שמכיל שדות מסוג שרירותי. שדה נוסף "@type" מכיל URI שמזהה את הסוג. לדוגמה: { "id": 1234, "@type": "types.example.com/standard/id" }.

סוף השדות הבלעדיים.
ייצוג ב-JSON 
{
  "name": string,
  "metadata": {
    "@type": string,
    field1: ...,
    ...
  },
  "done": boolean,

  // result
  "error": {
    object (Status)
  },
  "response": {
    "@type": string,
    field1: ...,
    ...
  }
  // Union type
}

שיטה: fileSearchStores.operations.get

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

נקודת קצה

get https://generativelanguage.googleapis.com/v1beta/{name=fileSearchStores/*/operations/*}

פרמטרים של נתיב

name string

השם של משאב הפעולה. הוא מקבל את הצורה fileSearchStores/{filesearchstore}/operations/{operation}.

גוף הבקשה

גוף הבקשה צריך להיות ריק.

גוף התשובה

אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכיל מופע של Operation.

משאב REST: ‏ fileSearchStores.upload.operations

משאב: פעולה

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

Fields
name string

השם שהוקצה על ידי השרת, שהוא ייחודי רק בתוך אותו שירות שהחזיר אותו במקור. אם משתמשים במיפוי ברירת המחדל של HTTP, הערך של name צריך להיות שם משאב שמסתיים ב-operations/{unique_id}.

metadata object

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

אובייקט שמכיל שדות מסוג שרירותי. שדה נוסף "@type" מכיל URI שמזהה את הסוג. לדוגמה: { "id": 1234, "@type": "types.example.com/standard/id" }.

done boolean

אם הערך הוא false, המשמעות היא שהפעולה עדיין מתבצעת. אם הערך הוא true, הפעולה הושלמה ואפשר להשתמש בערך error או response.

result Union type
תוצאת הפעולה, שיכולה להיות error או response תקין. אם done == false, אף אחד מהערכים error או response לא מוגדר. אם done == true, אפשר להגדיר בדיוק אחד מהערכים error או response. יכול להיות שחלק מהשירותים לא יספקו את התוצאה. הרשימה הבאה כוללת שדות שאי אפשר להשתמש בהם בו-זמנית. בכל תשובה יוגדר לכל היותר אחד מהשדות:
error object (Status)

תוצאת השגיאה של הפעולה במקרה של כשל או ביטול.

response object

התגובה הרגילה והמוצלחת של הפעולה. אם השיטה המקורית לא מחזירה נתונים במקרה של הצלחה, כמו Delete, התגובה היא google.protobuf.Empty. אם ה-method המקורית היא סטנדרטית Get/Create/Update, התשובה צריכה להיות המשאב. בשיטות אחרות, התשובה צריכה להיות מהסוג XxxResponse, כאשר Xxx הוא שם השיטה המקורי. לדוגמה, אם שם השיטה המקורי הוא TakeSnapshot(), סוג התגובה שמוסק הוא TakeSnapshotResponse.

אובייקט שמכיל שדות מסוג שרירותי. שדה נוסף "@type" מכיל URI שמזהה את הסוג. לדוגמה: { "id": 1234, "@type": "types.example.com/standard/id" }.

סוף השדות הבלעדיים.
ייצוג ב-JSON 
{
  "name": string,
  "metadata": {
    "@type": string,
    field1: ...,
    ...
  },
  "done": boolean,

  // result
  "error": {
    object (Status)
  },
  "response": {
    "@type": string,
    field1: ...,
    ...
  }
  // Union type
}

שיטה: fileSearchStores.upload.operations.get

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

נקודת קצה

get https://generativelanguage.googleapis.com/v1beta/{name=fileSearchStores/*/upload/operations/*}

פרמטרים של נתיב

name string

השם של משאב הפעולה. הוא מקבל את הצורה fileSearchStores/{filesearchstore}/upload/operations/{operation}.

גוף הבקשה

גוף הבקשה צריך להיות ריק.

גוף התשובה

אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכיל מופע של Operation.

שיטה: media.uploadToFileSearchStore

העלאת נתונים אל FileSearchStore, עיבוד מוקדם וחלוקה לחלקים לפני אחסון ב-FileSearchStore Document.

נקודת קצה

  • מזהה URI להעלאה, לבקשות להעלאת מדיה:
 post https://generativelanguage.googleapis.com/upload/v1beta/{fileSearchStoreName=fileSearchStores/*}:uploadToFileSearchStore
  • ‫URI של מטא-נתונים, לבקשות של מטא-נתונים בלבד:
 post https://generativelanguage.googleapis.com/v1beta/{fileSearchStoreName=fileSearchStores/*}:uploadToFileSearchStore

פרמטרים של נתיב

fileSearchStoreName string

חובה. אי אפשר לשנות. השם של FileSearchStore שאליו רוצים להעלות את הקובץ. דוגמה: fileSearchStores/my-file-search-store-123 התוצאה תהיה fileSearchStores/{filesearchstore}.

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה הבא:

Fields
displayName string

אופציונלי. השם המוצג של המסמך שנוצר.

customMetadata[] object (CustomMetadata)

מטא-נתונים בהתאמה אישית שרוצים לשייך לנתונים.

chunkingConfig object (ChunkingConfig)

אופציונלי. הגדרות שמציינות לשירות איך לחלק את הנתונים לחלקים. אם לא תציינו פרמטרים, השירות ישתמש בפרמטרים שמוגדרים כברירת מחדל.

mimeType string

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

גוף התשובה

אם הפעולה מצליחה, גוף התגובה מכיל נתונים במבנה הבא:

Fields
name string

השם שהוקצה על ידי השרת, שהוא ייחודי רק בתוך אותו שירות שהחזיר אותו במקור. אם משתמשים במיפוי ברירת המחדל של HTTP, הערך של name צריך להיות שם משאב שמסתיים ב-operations/{unique_id}.

metadata object

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

אובייקט שמכיל שדות מסוג שרירותי. שדה נוסף "@type" מכיל URI שמזהה את הסוג. לדוגמה: { "id": 1234, "@type": "types.example.com/standard/id" }.

done boolean

אם הערך הוא false, המשמעות היא שהפעולה עדיין מתבצעת. אם הערך הוא true, הפעולה הושלמה ואפשר להשתמש בערך error או response.

result Union type
תוצאת הפעולה, שיכולה להיות error או response תקין. אם done == false, אף אחד מהערכים error או response לא מוגדר. אם done == true, אפשר להגדיר בדיוק אחד מהערכים error או response. יכול להיות שחלק מהשירותים לא יספקו את התוצאה. הרשימה הבאה כוללת שדות שאי אפשר להשתמש בהם בו-זמנית. בכל תשובה יוגדר לכל היותר אחד מהשדות:
error object (Status)

תוצאת השגיאה של הפעולה במקרה של כשל או ביטול.

response object

התגובה הרגילה והמוצלחת של הפעולה. אם השיטה המקורית לא מחזירה נתונים במקרה של הצלחה, כמו Delete, התגובה היא google.protobuf.Empty. אם ה-method המקורית היא סטנדרטית Get/Create/Update, התשובה צריכה להיות המשאב. בשיטות אחרות, התשובה צריכה להיות מהסוג XxxResponse, כאשר Xxx הוא שם השיטה המקורי. לדוגמה, אם שם השיטה המקורי הוא TakeSnapshot(), סוג התגובה שמוסק הוא TakeSnapshotResponse.

אובייקט שמכיל שדות מסוג שרירותי. שדה נוסף "@type" מכיל URI שמזהה את הסוג. לדוגמה: { "id": 1234, "@type": "types.example.com/standard/id" }.

סוף השדות הבלעדיים.
ייצוג ב-JSON 
{
  "name": string,
  "metadata": {
    "@type": string,
    field1: ...,
    ...
  },
  "done": boolean,

  // result
  "error": {
    object (Status)
  },
  "response": {
    "@type": string,
    field1: ...,
    ...
  }
  // Union type
}