Docuents

مورد REST: corpora.documents

المرجع: مستند

السمة Document هي مجموعة من Chunk. ويمكن أن تحتوي Corpus على 10,000 Document كحد أقصى.

تمثيل JSON 
{
  "name": string,
  "displayName": string,
  "customMetadata": [
    {
      object (CustomMetadata)
    }
  ],
  "updateTime": string,
  "createTime": string
}
الحقول
name string

غير قابل للتغيير. المُعرّف. اسم المورد "Document". يمكن أن يحتوي رقم التعريف (الاسم باستثناء البادئة "corpora/*/documents/") على 40 حرفًا أبجديًا رقميًا صغيرًا أو شرطات (-). لا يمكن أن يبدأ المعرّف أو ينتهي بشرطة. إذا كان الاسم فارغًا عند الإنشاء، سيتم اشتقاق اسم فريد من displayName مع لاحقة عشوائية مكوّنة من 12 حرفًا. مثلاً: corpora/{corpus_id}/documents/my-awesome-doc-123a456b789c

displayName string

اختياريّ. تمثّل هذه السمة الاسم المعروض لـ Document الذي يمكن للمستخدمين قراءته. يجب ألا يزيد طول الاسم المعروض عن 512 حرفًا، بما في ذلك المسافات. مثال: "مستندات Semantic Retriever"

customMetadata[] object (CustomMetadata)

اختياريّ. البيانات الوصفية المخصّصة التي قدّمها المستخدم والمخزّنة كأزواج المفتاح/القيمة تُستخدَم لطلب البحث ويمكن أن تتضمّن Document 20 CustomMetadata بحدٍ أقصى.

updateTime string (Timestamp format)

النتائج فقط. الطابع الزمني لآخر تعديل لـ "Document"

طابع زمني بتنسيق RFC3339 حسب التوقيت العالمي المنسَّق (UTC) "زولو" بدقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z".

createTime string (Timestamp format)

النتائج فقط. الطابع الزمني لوقت إنشاء Document

طابع زمني بتنسيق RFC3339 حسب التوقيت العالمي المنسَّق (UTC) "زولو" بدقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z".

الطريقة: corpora.documents.create

تنشئ Document فارغة.

نقطة نهاية

منشور https://generativelanguage.googleapis.com/v1beta/{parent=corpora/*}/documents

مَعلمات المسار

parent string

مطلوب. اسم Corpus الذي سيتم إنشاء Document فيه مثال: corpora/my-corpus-123 تأخذ الشكل corpora/{corpora}.

نص الطلب

يحتوي نص الطلب على مثال Document.

نص الاستجابة

في حال نجاح الإجراء، يحتوي نص الاستجابة على مثيل Document تم إنشاؤه حديثًا.

الطريقة: corpora.documents.list

يسرد جميع Document في Corpus.

نقطة نهاية

الحصول على https://generativelanguage.googleapis.com/v1beta/{parent=corpora/*}/documents

مَعلمات المسار

parent string

مطلوب. اسم Corpus الذي يحتوي على Document مثال: corpora/my-corpus-123 تأخذ الشكل corpora/{corpora}.

معامِلات طلب البحث

pageSize integer

اختياريّ. الحد الأقصى لعدد Document ثانية المطلوب عرضها (لكل صفحة). قد تعرض الخدمة عددًا أقل من Document.

وفي حال عدم تحديد قيمة السمة، سيتم إرجاع 10 Document كحدّ أقصى. الحدّ الأقصى للحجم هو 20 Document ثانية لكل صفحة.

pageToken string

اختياريّ. رمز مميّز للصفحة، تم تلقّيه من استدعاء سابق لتطبيق "documents.list".

يمكنك تقديم nextPageToken الذي تم عرضه في الردّ كوسيطة للطلب التالي لاسترداد الصفحة التالية.

عند التقسيم على صفحات، يجب أن تتطابق جميع المَعلمات الأخرى المقدَّمة إلى documents.list مع الاستدعاء الذي قدّم الرمز المميّز للصفحة.

نص الطلب

يجب أن يكون نص الطلب فارغًا.

نص الاستجابة

رد من documents.list يحتوي على قائمة مقسّمة على صفحات تضم Document. يتم فرز Document تصاعديًا document.create_time.

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

الحقول
documents[] object (Document)

قيمتا Document التي تم إرجاعها

nextPageToken string

رمز مميز يمكن إرساله على شكل pageToken لاسترداد الصفحة التالية. إذا تم حذف هذا الحقل، يعني هذا أنّه لا يتوفّر المزيد من الصفحات.

تمثيل JSON 
{
  "documents": [
    {
      object (Document)
    }
  ],
  "nextPageToken": string
}

الطريقة: corpora.documents.query

لإجراء بحث دلالي عبر Document.

نقطة نهاية

منشور https://generativelanguage.googleapis.com/v1beta/{name=corpora/*/documents/*}:query

مَعلمات المسار

name string

مطلوب. اسم Document المطلوب طلبه. مثال: corpora/my-corpus-123/documents/the-doc-abc تأخذ الشكل corpora/{corpora}/documents/{document}.

نص الطلب

يحتوي نص الطلب على بيانات بالبنية التالية:

الحقول
query string

مطلوب. سلسلة طلب بحث لإجراء بحث دلالي.

resultsCount integer

اختياريّ. الحد الأقصى لعدد Chunks المطلوب عرضها. قد تعرض الخدمة عددًا أقل من Chunk.

وفي حال عدم تحديد قيمة السمة، سيتم إرجاع 10 Chunk كحدّ أقصى. الحد الأقصى لعدد النتائج المحددة هو 100.

metadataFilters[] object (MetadataFilter)

اختياريّ. طبِّق الفلتر بحثًا عن بيانات Chunk الوصفية. يجب أن يكون كل عنصر MetadataFilter متوافقًا مع مفتاح فريد. يتم ربط كائنات MetadataFilter متعددة بواسطة أحرف "AND" منطقية.

ملاحظة: لا يمكن إجراء فلترة على مستوى Document لهذا الطلب لأنّه سبق أن تم تحديد اسم Document.

مثال على طلب البحث: (year >= 2020 OR year < 2010) AND (genre = تأكّد OR genre = action)

قائمة الكائنات MetadataFilter: البيانات الوصفية لفلاتر = [ {key = "chunk.custom_metadata.year" الشروط = [{int_value = 2020, العملية = GREATER_EQUAL}، {int_value = 2010, operation = LESS}}, {key = "chunk.custom_metadata.genre" الشروط = [{stringValue = "drama", العملية = EQUAL}، {stringValue = "action"، العملية = EQUAL}}]

مثال على طلب بحث لنطاق رقمي من القيم: (year > 2015 AND year <= 2020)

قائمة الكائنات MetadataFilter: البيانات الوصفية لفلاتر = [ {key = "chunk.custom_metadata.year" conditions = [{int_value = 2015, operation = GREATER}]}, {key = &quot;chunk.custom_metadata.year&quot; الشروط = [{int_value = 2020, العملية = LESS_EQUAL}]}]

ملاحظة: تتوفر أحرف "و" للمفتاح نفسه للقيم الرقمية فقط. تتيح قيم السلسلة استخدام "OR" للمفتاح نفسه فقط.

نص الاستجابة

ردّ من documents.query يحتوي على قائمة بالأجزاء ذات الصلة

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

الحقول
relevantChunks[] object (RelevantChunk)

الأجزاء ذات الصلة التي تم إرجاعها.

تمثيل JSON 
{
  "relevantChunks": [
    {
      object (RelevantChunk)
    }
  ]
}

الطريقة: corpora.documents.get

يتيح هذا الخيار الحصول على معلومات عن Document محدّد.

نقطة نهاية

الحصول على https://generativelanguage.googleapis.com/v1beta/{name=corpora/*/documents/*}

مَعلمات المسار

name string

مطلوب. اسم Document المطلوب استرداده. مثال: corpora/my-corpus-123/documents/the-doc-abc تأخذ الشكل corpora/{corpora}/documents/{document}.

نص الطلب

يجب أن يكون نص الطلب فارغًا.

نص الاستجابة

إذا كانت الاستجابة ناجحة، يحتوي نص الاستجابة على مثال Document.

الطريقة: corpora.documents.patch

يعدِّل Document.

نقطة نهاية

رمز تصحيح https://generativelanguage.googleapis.com/v1beta/{document.name=corpora/*/documents/*}

PATCH https://generativelanguage.googleapis.com/v1beta/{document.name=corpora/*/documents/*}

مَعلمات المسار

document.name string

غير قابل للتغيير. المُعرّف. اسم المورد "Document". يمكن أن يحتوي المعرّف (الاسم باستثناء البادئة "corpora/*/documents/") على 40 حرفًا أبجديًا رقميًا صغيرًا أو شرطات (-). لا يمكن أن يبدأ المعرّف أو ينتهي بشرطة. إذا كان الاسم فارغًا عند الإنشاء، سيتم اشتقاق اسم فريد من displayName مع لاحقة عشوائية مكوّنة من 12 حرفًا. مثال: corpora/{corpus_id}/documents/my-awesome-doc-123a456b789c تأخذ الشكل corpora/{corpora}/documents/{document}.

معامِلات طلب البحث

updateMask string (FieldMask format)

مطلوب. قائمة الحقول المطلوب تعديلها. في الوقت الحالي، يتيح هذا التحديث تحديث displayName وcustomMetadata فقط.

هذه قائمة مفصولة بفواصل تضم أسماء الحقول المؤهلة بالكامل. مثال: "user.displayName,photo"

نص الطلب

يحتوي نص الطلب على مثال Document.

نص الاستجابة

إذا كانت الاستجابة ناجحة، يحتوي نص الاستجابة على مثال Document.

الطريقة: corpora.documents.delete

يؤدي هذا الإجراء إلى حذف Document.

نقطة نهاية

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

مَعلمات المسار

name string

مطلوب. اسم المورد Document المطلوب حذفه. مثال: corpora/my-corpus-123/documents/the-doc-abc تأخذ الشكل corpora/{corpora}/documents/{document}.

معامِلات طلب البحث

force boolean

اختياريّ. في حال ضبط السياسة على "صحيح"، سيتم أيضًا حذف أي عناصر Chunk وكائنات مرتبطة بهذا Document.

وفي حال كانت القيمة "خطأ" (الخيار التلقائي)، سيتم عرض خطأ FAILED_PRECONDITION إذا كانت السمة Document تحتوي على أي قيم Chunk.

نص الطلب

يجب أن يكون نص الطلب فارغًا.

نص الاستجابة

إذا كانت الاستجابة ناجحة، يكون نص الاستجابة فارغًا.

CustomMetadata

البيانات الوصفية التي قدّمها المستخدم والمخزّنة كأزواج المفتاح/القيمة

تمثيل JSON 
{
  "key": string,

  // Union field value can be only one of the following:
  "stringValue": string,
  "stringListValue": {
    object (StringList)
  },
  "numericValue": number
  // End of list of possible types for union field value.
}
الحقول
key string

مطلوب. مفتاح بيانات التعريف المطلوب تخزينها.

حقل الاتحاد value.

يمكن أن يكون value واحدًا فقط مما يلي:

stringValue string

قيمة السلسلة للبيانات الوصفية المطلوب تخزينها.

stringListValue object (StringList)

قيمة StringList للبيانات الوصفية المطلوب تخزينها.

numericValue number

القيمة الرقمية للبيانات الوصفية المطلوب تخزينها.

StringList

قيم سلسلة قدّمها المستخدم مخصصة لمفتاح بيانات وصفية واحد

تمثيل JSON 
{
  "values": [
    string
  ]
}
الحقول
values[] string

قيم السلسلة للبيانات الوصفية المطلوب تخزينها.