Documents

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

لإنشاء Document فارغ

نقطة نهاية

post https://generativelanguage.googleapis.com/v1beta/{parent=corpora/*}/documents

يستخدِم عنوان URL بنية تحويل ترميز gRPC.

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

parent string

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

نص الطلب

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

الحقول
name string

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

displayName string

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

customMetadata[] object (CustomMetadata)

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

نص الاستجابة

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

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

تُجري عملية بحث دلالي على Document.

نقطة نهاية

post https://generativelanguage.googleapis.com/v1beta/{name=corpora/*/documents/*}:query

يستخدِم عنوان URL بنية تحويل ترميز gRPC.

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

name string

مطلوب. اسم Document المطلوب إجراء طلب بحث عنه مثال: corpora/my-corpus-123/documents/the-doc-abc يكون على الشكل corpora/{corpora}/documents/{document}.

نص الطلب

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

الحقول
query string

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

resultsCount integer

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

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

metadataFilters[] object (MetadataFilter)

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

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

مثال على طلب البحث: (year >= 2020 OR year < 2010) AND (genre = drama OR genre = action)

MetadataFilter قائمة العناصر: metadataFilters = [ {key = "chunk.custom_metadata.year" conditions = [{int_value = 2020, operation = GREATER_EQUAL}, {int_value = 2010, operation = LESS}}, {key = "chunk.custom_metadata.genre" conditions = [{stringValue = "drama", operation = EQUAL}, {stringValue = "action", operation = EQUAL}}]

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

MetadataFilter قائمة العناصر: metadataFilters = [ {key = "chunk.custom_metadata.year" conditions = [{int_value = 2015, operation = GREATER}]}, {key = "chunk.custom_metadata.year" conditions = [{int_value = 2020, operation = LESS_EQUAL}]}]

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

نص الاستجابة

استجابة من documents.query تحتوي على قائمة بالمقاطع ذات الصلة

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

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

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

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

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

يتم إدراج جميع Document في Corpus.

نقطة نهاية

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

يستخدِم عنوان URL بنية تحويل ترميز gRPC.

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

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.get

الحصول على معلومات عن Document معيّن

نقطة نهاية

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

يستخدِم عنوان URL بنية تحويل ترميز gRPC.

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

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/*}

يستخدِم عنوان URL بنية تحويل ترميز gRPC.

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

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.

الحقول
displayName string

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

customMetadata[] object (CustomMetadata)

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

نص الاستجابة

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

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

لحذف Document

نقطة نهاية

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

يستخدِم عنوان URL بنية تحويل ترميز gRPC.

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

name string

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

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

force boolean

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

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

نص الطلب

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

نص الاستجابة

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

مورد REST: corpora.documents

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

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

الحقول
name string

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

displayName string

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

customMetadata[] object (CustomMetadata)

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

updateTime string (Timestamp format)

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

يستخدم معيار 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"

createTime string (Timestamp format)

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

يستخدم معيار 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"

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

CustomMetadata

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

الحقول
key string

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

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

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

stringListValue object (StringList)

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

numericValue number

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

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

  // value
  "stringValue": string,
  "stringListValue": {
    object (StringList)
  },
  "numericValue": number
  // Union type
}

StringList

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

الحقول
values[] string

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

تمثيل JSON
{
  "values": [
    string
  ]
}