File Search Stores

رابط برنامه‌نویسی کاربردی جستجوی فایل (File Search API) یک سرویس پاسخگویی به پرسش و پاسخ میزبانی‌شده برای ساخت سیستم‌های بازیابی افزوده نسل (RAG) با استفاده از زیرساخت گوگل ارائه می‌دهد.

روش: media.uploadToFileSearchStore

داده‌ها را در FileSearchStore آپلود می‌کند، قبل از ذخیره آنها در یک سند FileSearchStore، پیش‌پردازش‌ها و تکه‌ها را انجام می‌دهد.

نقطه پایانی

  • آپلود URI، برای درخواست‌های آپلود رسانه:
    • پست https: / /generativelanguage.googleapis.com /upload /v1beta /{fileSearchStoreName=fileSearchStores /*}:uploadToFileSearchStore
  • آدرس URL فراداده، برای درخواست‌های فقط فراداده:
    • پست https: / /generativelanguage.googleapis.com /v1beta /{fileSearchStoreName=fileSearchStores /*}:uploadToFileSearchStore

    پارامترهای مسیر

    string fileSearchStoreName

    اجباری. تغییرناپذیر. نام FileSearchStore که قرار است فایل در آن آپلود شود. مثال: fileSearchStores/my-file-search-store-123 این مقدار به شکل fileSearchStores/{filesearchstore} است.

    درخواست بدنه

    بدنه درخواست شامل داده‌هایی با ساختار زیر است:

    فیلدها
    string displayName

    اختیاری. نام سند ایجاد شده را نمایش می‌دهد.

    شیء customMetadata[] object ( CustomMetadata )

    فراداده‌های سفارشی که باید با داده‌ها مرتبط شوند.

    شیء chunkingConfig object ( ChunkingConfig )

    اختیاری. پیکربندی برای اطلاع‌رسانی به سرویس در مورد نحوه‌ی قطعه‌بندی داده‌ها. در صورت عدم ارائه، سرویس از پارامترهای پیش‌فرض استفاده خواهد کرد.

    string mimeType

    اختیاری. نوع MIME داده‌ها. در صورت عدم ارائه، از محتوای آپلود شده استنباط خواهد شد.

    بدنه پاسخ

    این یک کپی از google.longrunning.Operation است. ما باید آن را کپی کنیم زیرا برای تعامل با scotty، باید یک فیلد مخصوص scotty اضافه کنیم که نمی‌توان آن را در پروتوتایپ Operation سطح بالا اضافه کرد.

    در صورت موفقیت، بدنه پاسخ شامل داده‌هایی با ساختار زیر است:

    فیلدها
    string name

    The server-assigned name, which is only unique within the same service that originally returns it. If you use the default HTTP mapping, the name should be a resource name ending with operations/{unique_id} .

    object metadata

    فراداده‌های مختص سرویس مرتبط با عملیات. معمولاً شامل اطلاعات پیشرفت و فراداده‌های رایج مانند زمان ایجاد است. برخی از سرویس‌ها ممکن است چنین فراداده‌ای را ارائه ندهند. هر متدی که یک عملیات طولانی مدت را برمی‌گرداند، باید نوع فراداده را، در صورت وجود، مستند کند.

    یک شیء حاوی فیلدهایی از نوع دلخواه. یک فیلد اضافی "@type" حاوی یک URI است که نوع را مشخص می‌کند. مثال: { "id": 1234, "@type": "types.example.com/standard/id" } .

    boolean done

    اگر مقدار آن false باشد، به این معنی است که عملیات هنوز در حال انجام است. اگر true ، عملیات تکمیل شده و error یا response در دسترس است.

    result Union type
    نتیجه عملیات، که می‌تواند یک error یا یک response معتبر باشد. اگر done == false ، نه error و نه response تنظیم نمی‌شوند. اگر done == true ، دقیقاً یکی از error یا response می‌تواند تنظیم شود. برخی از سرویس‌ها ممکن است نتیجه را ارائه ندهند. result فقط می‌تواند یکی از موارد زیر باشد:
    شیء error object ( Status )

    نتیجه خطای عملیات در صورت عدم موفقیت یا لغو.

    object response

    پاسخ عادی و موفقیت‌آمیز عملیات. اگر متد اصلی هیچ داده‌ای مانند Delete در صورت موفقیت برنگرداند، پاسخ google.protobuf.Empty خواهد بود. اگر متد اصلی Get / Create / Update استاندارد باشد، پاسخ باید resource باشد. برای متدهای دیگر، پاسخ باید از نوع 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.create

    یک FileSearchStore خالی ایجاد می‌کند.

    نقطه پایانی

    پست https: / /generativelanguage.googleapis.com /v1beta /fileSearchStores

    درخواست بدنه

    بدنه درخواست شامل نمونه‌ای از FileSearchStore است.

    فیلدها
    string displayName

    اختیاری. نام نمایشی قابل خواندن توسط انسان برای FileSearchStore . نام نمایشی نباید بیش از ۵۱۲ کاراکتر، شامل فاصله‌ها، باشد. مثال: "Docs on Semantic Retriever"

    بدنه پاسخ

    در صورت موفقیت، بدنه پاسخ شامل یک نمونه تازه ایجاد شده از FileSearchStore است.

    روش: fileSearchStores.delete

    یک FileSearchStore حذف می‌کند.

    نقطه پایانی

    حذف https: / /generativelanguage.googleapis.com /v1beta /{name=fileSearchStores /*}

    پارامترهای مسیر

    string name

    الزامی. نام منبع FileSearchStore . مثال: fileSearchStores/my-file-search-store-123 این مقدار به شکل fileSearchStores/{filesearchstore} است.

    پارامترهای پرس و جو

    force boolean

    اختیاری. اگر روی true تنظیم شود، هر Document و شیء مرتبط با این FileSearchStore نیز حذف خواهد شد.

    اگر مقدار آن false باشد (پیش‌فرض)، در صورتی که FileSearchStore حاوی هر نوع Document باشد، خطای FAILED_PRECONDITION برگردانده می‌شود.

    درخواست بدنه

    بدنه درخواست باید خالی باشد.

    بدنه پاسخ

    در صورت موفقیت، بدنه پاسخ یک شیء JSON خالی خواهد بود.

    روش: fileSearchStores.get

    اطلاعات مربوط به یک FileSearchStore خاص را دریافت می‌کند.

    نقطه پایانی

    دریافت https: / /generativelanguage.googleapis.com /v1beta /{name=fileSearchStores /*}

    پارامترهای مسیر

    string name

    الزامی. نام FileSearchStore . مثال: fileSearchStores/my-file-search-store-123 این تابع فرم fileSearchStores/{filesearchstore} را می‌گیرد.

    درخواست بدنه

    بدنه درخواست باید خالی باشد.

    بدنه پاسخ

    در صورت موفقیت، بدنه پاسخ شامل نمونه‌ای از FileSearchStore خواهد بود.

    روش: fileSearchStores.list

    تمام FileSearchStores متعلق به کاربر را لیست می‌کند.

    نقطه پایانی

    دریافت https: / /generativelanguage.googleapis.com /v1beta /fileSearchStores

    پارامترهای پرس و جو

    integer pageSize

    اختیاری. حداکثر تعداد FileSearchStores برای برگرداندن (در هر صفحه). این سرویس ممکن است FileSearchStores کمتری برگرداند.

    اگر مشخص نشود، حداکثر ۱۰ FileSearchStores برگردانده خواهد شد. حداکثر اندازه مجاز ۲۰ FileSearchStores در هر صفحه است.

    string pageToken

    اختیاری. یک توکن صفحه، که از فراخوانی قبلی fileSearchStores.list دریافت شده است.

    nextPageToken برگردانده شده در پاسخ را به عنوان آرگومان برای درخواست بعدی جهت بازیابی صفحه بعدی ارائه دهید.

    هنگام صفحه‌بندی، تمام پارامترهای دیگر ارائه شده به fileSearchStores.list باید با فراخوانی که توکن صفحه را ارائه داده است، مطابقت داشته باشند.

    درخواست بدنه

    بدنه درخواست باید خالی باشد.

    بدنه پاسخ

    پاسخ از fileSearchStores.list حاوی لیست صفحه‌بندی‌شده‌ای از FileSearchStores . نتایج بر اساس fileSearchStore.create_time صعودی مرتب شده‌اند.

    در صورت موفقیت، بدنه پاسخ شامل داده‌هایی با ساختار زیر است:

    فیلدها
    شیء fileSearchStores[] object ( FileSearchStore )

    پارچه‌های برگشتی فروشگاه‌ها.

    string nextPageToken

    یک توکن، که می‌تواند به عنوان pageToken برای بازیابی صفحه بعدی ارسال شود. اگر این فیلد حذف شود، صفحات بیشتری وجود نخواهد داشت.

    نمایش JSON 
    {
  "fileSearchStores": [
    {
      object (FileSearchStore)
    }
  ],
  "nextPageToken": string
}

    روش: fileSearchStores.importFile

    یک File از File Service به FileSearchStore وارد می‌کند.

    نقطه پایانی

    پست https: / /generativelanguage.googleapis.com /v1beta /{fileSearchStoreName=fileSearchStores /*}:importFile

    پارامترهای مسیر

    string fileSearchStoreName

    الزامی. تغییرناپذیر. نام FileSearchStore که قرار است فایل به آن وارد شود. مثال: fileSearchStores/my-file-search-store-123 این مقدار به شکل fileSearchStores/{filesearchstore} است.

    درخواست بدنه

    بدنه درخواست شامل داده‌هایی با ساختار زیر است:

    فیلدها
    string fileName

    الزامی. نام File که قرار است وارد شود. مثال: files/abc-123

    شیء customMetadata[] object ( CustomMetadata )

    فراداده‌های سفارشی که باید با فایل مرتبط شوند.

    شیء chunkingConfig object ( ChunkingConfig )

    اختیاری. پیکربندی برای اینکه به سرویس بگویید چگونه فایل را تکه‌تکه کند. اگر ارائه نشود، سرویس از پارامترهای پیش‌فرض استفاده خواهد کرد.

    بدنه پاسخ

    در صورت موفقیت، بدنه پاسخ شامل نمونه‌ای از Operation است.

    منبع REST: fileSearchStores.operations

    منبع: عملیات

    این منبع نشان دهنده یک عملیات طولانی مدت است که نتیجه یک فراخوانی API شبکه است.

    فیلدها
    string name

    نام اختصاص داده شده توسط سرور، که فقط در همان سرویسی که در ابتدا آن را برمی‌گرداند، منحصر به فرد است. اگر از نگاشت پیش‌فرض HTTP استفاده می‌کنید، name باید نام منبعی باشد که به operations/{unique_id} ختم می‌شود.

    object metadata

    فراداده‌های مختص سرویس مرتبط با عملیات. معمولاً شامل اطلاعات پیشرفت و فراداده‌های رایج مانند زمان ایجاد است. برخی از سرویس‌ها ممکن است چنین فراداده‌ای را ارائه ندهند. هر متدی که یک عملیات طولانی مدت را برمی‌گرداند، باید نوع فراداده را، در صورت وجود، مستند کند.

    یک شیء حاوی فیلدهایی از نوع دلخواه. یک فیلد اضافی "@type" حاوی یک URI است که نوع را مشخص می‌کند. مثال: { "id": 1234, "@type": "types.example.com/standard/id" } .

    boolean done

    اگر مقدار آن false باشد، به این معنی است که عملیات هنوز در حال انجام است. اگر true ، عملیات تکمیل شده و error یا response در دسترس است.

    result Union type
    نتیجه عملیات، که می‌تواند یک error یا یک response معتبر باشد. اگر done == false ، نه error و نه response تنظیم نمی‌شوند. اگر done == true ، دقیقاً یکی از error یا response می‌تواند تنظیم شود. برخی از سرویس‌ها ممکن است نتیجه را ارائه ندهند. result فقط می‌تواند یکی از موارد زیر باشد:
    شیء error object ( Status )

    نتیجه خطای عملیات در صورت عدم موفقیت یا لغو.

    object response

    پاسخ عادی و موفقیت‌آمیز عملیات. اگر متد اصلی هیچ داده‌ای مانند Delete در صورت موفقیت برنگرداند، پاسخ google.protobuf.Empty خواهد بود. اگر متد اصلی Get / Create / Update استاندارد باشد، پاسخ باید resource باشد. برای متدهای دیگر، پاسخ باید از نوع 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 استفاده کنند.

    نقطه پایانی

    دریافت https: / /generativelanguage.googleapis.com /v1beta /{name=fileSearchStores /* /operations /*}

    پارامترهای مسیر

    string name

    نام منبع عملیات. این منبع شکلی به صورت fileSearchStores/{filesearchstore}/operations/{operation} ‎ دارد.

    درخواست بدنه

    بدنه درخواست باید خالی باشد.

    بدنه پاسخ

    در صورت موفقیت، بدنه پاسخ شامل نمونه‌ای از Operation است.

    منبع REST: fileSearchStores.upload.operations

    منبع: عملیات

    این منبع نشان دهنده یک عملیات طولانی مدت است که نتیجه یک فراخوانی API شبکه است.

    فیلدها
    string name

    نام اختصاص داده شده توسط سرور، که فقط در همان سرویسی که در ابتدا آن را برمی‌گرداند، منحصر به فرد است. اگر از نگاشت پیش‌فرض HTTP استفاده می‌کنید، name باید نام منبعی باشد که به operations/{unique_id} ختم می‌شود.

    object metadata

    فراداده‌های مختص سرویس مرتبط با عملیات. معمولاً شامل اطلاعات پیشرفت و فراداده‌های رایج مانند زمان ایجاد است. برخی از سرویس‌ها ممکن است چنین فراداده‌ای را ارائه ندهند. هر متدی که یک عملیات طولانی مدت را برمی‌گرداند، باید نوع فراداده را، در صورت وجود، مستند کند.

    یک شیء حاوی فیلدهایی از نوع دلخواه. یک فیلد اضافی "@type" حاوی یک URI است که نوع را مشخص می‌کند. مثال: { "id": 1234, "@type": "types.example.com/standard/id" } .

    boolean done

    اگر مقدار آن false باشد، به این معنی است که عملیات هنوز در حال انجام است. اگر true ، عملیات تکمیل شده و error یا response در دسترس است.

    result Union type
    The operation result, which can be either an error or a valid response . If done == false , neither error nor response is set. If done == true , exactly one of error or response can be set. Some services might not provide the result. result can be only one of the following:
    شیء error object ( Status )

    نتیجه خطای عملیات در صورت عدم موفقیت یا لغو.

    object response

    پاسخ عادی و موفقیت‌آمیز عملیات. اگر متد اصلی هیچ داده‌ای مانند Delete در صورت موفقیت برنگرداند، پاسخ google.protobuf.Empty خواهد بود. اگر متد اصلی Get / Create / Update استاندارد باشد، پاسخ باید resource باشد. برای متدهای دیگر، پاسخ باید از نوع 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 استفاده کنند.

    نقطه پایانی

    دریافت https: / /generativelanguage.googleapis.com /v1beta /{name=fileSearchStores /* /upload /operations /*}

    پارامترهای مسیر

    string name

    نام منبع عملیات. این منبع فرم fileSearchStores/{filesearchstore}/upload/operations/{operation} را می‌گیرد.

    درخواست بدنه

    بدنه درخواست باید خالی باشد.

    بدنه پاسخ

    در صورت موفقیت، بدنه پاسخ شامل نمونه‌ای از Operation است.

    منبع REST: fileSearchStores

    منبع: FileSearchStore

    یک FileSearchStore مجموعه‌ای از Document ها است.

    فیلدها
    string name

    فقط خروجی. تغییرناپذیر. شناسه. نام منبع FileSearchStore . این یک شناسه است (نامی به جز پیشوند "fileSearchStores/") که می‌تواند تا ۴۰ کاراکتر حروف کوچک و عددی یا خط تیره (-) داشته باشد. این فقط خروجی است. نام منحصر به فرد از displayName به همراه یک پسوند تصادفی ۱۲ کاراکتری گرفته می‌شود. مثال: fileSearchStores/my-awesome-file-search-store-123a456b789c اگر displayName ارائه نشود، نام به طور تصادفی تولید می‌شود.

    string displayName

    اختیاری. نام نمایشی قابل خواندن توسط انسان برای FileSearchStore . نام نمایشی نباید بیش از ۵۱۲ کاراکتر، شامل فاصله‌ها، باشد. مثال: "Docs on Semantic Retriever"

    رشته‌ی createTime string ( Timestamp format)

    فقط خروجی. مهر زمانیِ ایجاد FileSearchStore .

    از RFC 3339 استفاده می‌کند، که در آن خروجی تولید شده همیشه به صورت Z-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "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-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "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 است.

    نمایش JSON 
    {
  "name": string,
  "displayName": string,
  "createTime": string,
  "updateTime": string,
  "activeDocumentsCount": string,
  "pendingDocumentsCount": string,
  "failedDocumentsCount": string,
  "sizeBytes": string
}