مكتبة عميل Azure الذكاء الاصطناعي Search ل JavaScript - الإصدار 12.1.0

Azure الذكاء الاصطناعي Search (المعروف سابقا باسم "Azure Cognitive Search") هو نظام أساسي لاسترداد المعلومات مدعوم من الذكاء الاصطناعي يساعد المطورين على بناء تجارب بحث غنية وتطبيقات الذكاء الاصطناعي توليدية تجمع بين نماذج اللغات الكبيرة وبيانات المؤسسة.

خدمة Azure الذكاء الاصطناعي Search مناسبة تماما لسيناريوهات التطبيق التالية:

• دمج أنواع المحتويات المتنوعة في فهرس واحد قابل للبحث. لتعبئة فهرس، يمكنك دفع مستندات JSON التي تحتوي على المحتوى الخاص بك، أو إذا كانت بياناتك موجودة بالفعل في Azure، قم بإنشاء مفهرس لسحب البيانات تلقائيا.
• إرفاق مجموعات المهارات بمفهرس لإنشاء محتوى قابل للبحث من الصور والمستندات غير المنظمة. تستفيد مجموعة المهارات من واجهات برمجة التطبيقات من Azure الذكاء الاصطناعي Services من أجل التعرف البصري على الحروف المضمنة، والتعرف على الكيان، واستخراج العبارة الرئيسية، واكتشاف اللغة، وترجمة النص، وتحليل التوجه. يمكنك أيضا إضافة مهارات مخصصة لدمج المعالجة الخارجية للمحتوى أثناء استيعاب البيانات.
• في تطبيق عميل البحث، نفذ منطق الاستعلام وتجارب المستخدم المشابهة لمحركات البحث التجارية على الويب وتطبيقات نمط الدردشة.

استخدم مكتبة عميل @azure/search-documents من أجل:

• إرسال الاستعلامات باستخدام المتجهات والكلمة الأساسية ونماذج الاستعلام المختلط.
• تنفيذ الاستعلامات المصفاة لبيانات التعريف أو البحث الجيوفضائي أو التنقل المتوازى أو لتضييق النتائج استنادا إلى معايير التصفية.
• إنشاء فهارس البحث وإدارتها.
• تحميل المستندات وتحديثها في فهرس البحث.
• إنشاء وإدارة المفهرسات التي تسحب البيانات من Azure إلى فهرس.
• إنشاء وإدارة مجموعات المهارات التي تضيف إثراء الذكاء الاصطناعي إلى استيعاب البيانات.
• إنشاء المحللات وإدارتها لتحليل النص المتقدم أو المحتوى متعدد اللغات.
• تحسين النتائج من خلال التصنيف الدلالي وملفات تعريف النقاط لعامل في منطق العمل أو الحداثة.

الارتباطات الرئيسية:

• التعليمات البرمجية المصدر
• حزمة (NPM)
• الوثائق المرجعية لواجهة برمجة التطبيقات
• وثائق واجهة برمجة تطبيقات REST
• وثائق Product
• عينات

الشروع

تثبيت حزمة @azure/search-documents

npm install @azure/search-documents

البيئات المدعومة حاليا

• إصدارات LTS من Node.js
• أحدث إصدارات Safari وChrome وMicrosoft Edge وFirefox.

راجع نهج دعم للحصول على مزيد من التفاصيل.

المتطلبات المسبقه

• اشتراك Azure
• خدمة البحث

لإنشاء خدمة بحث جديدة، يمكنك استخداممدخل Azure أو Azure PowerShellأوAzure CLI . فيما يلي مثال باستخدام Azure CLI لإنشاء مثيل مجاني للبدء:

az search service create --name <mysearch> --resource-group <mysearch-rg> --sku free --location westus

راجع اختيار مستوى تسعير لمزيد من المعلومات حول الخيارات المتاحة.

مصادقة العميل

للتفاعل مع خدمة البحث، ستحتاج إلى إنشاء مثيل لفئة العميل المناسبة: SearchClient للبحث في المستندات المفهرسة أو SearchIndexClient لإدارة الفهارس أو SearchIndexerClient لتتبع ارتباطات مصادر البيانات وتحميل مستندات البحث في فهرس. لإنشاء مثيل لكائن عميل، ستحتاج إلى نقطة نهاية أدوار Azure أو مفتاح واجهة برمجة تطبيقات . يمكنك الرجوع إلى الوثائق لمزيد من المعلومات حول نهج المصادقة المدعومة مع خدمة البحث.

الحصول على مفتاح واجهة برمجة التطبيقات

يمكن أن يكون مفتاح واجهة برمجة التطبيقات نهجا أسهل للبدء به لأنه لا يتطلب تعيينات أدوار موجودة مسبقا.

يمكنك الحصول على نقطة النهاية ومفتاح واجهة برمجة تطبيقات من خدمة البحث في مدخل Microsoft Azure . يرجى الرجوع إلى وثائق للحصول على إرشادات حول كيفية الحصول على مفتاح API.

بدلا من ذلك، يمكنك استخدام الأمر Azure CLI التالي لاسترداد مفتاح API من خدمة البحث:

az search admin-key show --resource-group <your-resource-group-name> --service-name <your-resource-name>

هناك نوعان من المفاتيح المستخدمة للوصول إلى خدمة البحث: مفاتيحالمسؤول (للقراءة والكتابة) ومفاتيحالاستعلام (للقراءة فقط). يعد تقييد الوصول والعمليات في تطبيقات العميل أمرا ضروريا لحماية أصول البحث في خدمتك. استخدم دائما مفتاح استعلام بدلا من مفتاح مسؤول لأي استعلام ينشأ من تطبيق عميل.

ملاحظة: يسترد مثال مقتطف Azure CLI أعلاه مفتاح مسؤول بحيث يكون من الأسهل البدء في استكشاف واجهات برمجة التطبيقات، ولكن يجب إدارتها بعناية.

بمجرد أن يكون لديك مفتاح api، يمكنك استخدامه كما يلي:

const {
  SearchClient,
  SearchIndexClient,
  SearchIndexerClient,
  AzureKeyCredential,
} = require("@azure/search-documents");

// To query and manipulate documents
const searchClient = new SearchClient(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<apiKey>")
);

// To manage indexes and synonymmaps
const indexClient = new SearchIndexClient("<endpoint>", new AzureKeyCredential("<apiKey>"));

// To manage indexers, datasources and skillsets
const indexerClient = new SearchIndexerClient("<endpoint>", new AzureKeyCredential("<apiKey>"));

المصادقة في سحابة وطنية

للمصادقة في National Cloud، ستحتاج إلى إجراء الإضافات التالية إلى تكوين العميل الخاص بك:

• تعيين Audience في SearchClientOptions

const {
  SearchClient,
  SearchIndexClient,
  SearchIndexerClient,
  AzureKeyCredential,
  KnownSearchAudience,
} = require("@azure/search-documents");

// To query and manipulate documents
const searchClient = new SearchClient(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<apiKey>"),
  {
    audience: KnownSearchAudience.AzureChina,
  }
);

// To manage indexes and synonymmaps
const indexClient = new SearchIndexClient("<endpoint>", new AzureKeyCredential("<apiKey>"), {
  audience: KnownSearchAudience.AzureChina,
});

// To manage indexers, datasources and skillsets
const indexerClient = new SearchIndexerClient("<endpoint>", new AzureKeyCredential("<apiKey>"), {
  audience: KnownSearchAudience.AzureChina,
});

المفاهيم الرئيسية

تحتوي خدمة Azure الذكاء الاصطناعي Search على فهرس واحد أو أكثر يوفر تخزينا مستمرا للبيانات القابلة للبحث في شكل مستندات JSON. (إذا كنت جديدا على البحث، يمكنك إجراء تشبيه تقريبي جدا بين الفهارس وجداول قاعدة البيانات.) تعرض مكتبة عميل @azure/search-documents العمليات على هذه الموارد من خلال ثلاثة أنواع رئيسية من العملاء.

• يساعد SearchClient في:

  • البحث المستندات المفهرسة باستخدام استعلامات متجهات واستعلامات الكلمات الأساسية والاستعلامات المختلطة
  • عوامل تصفية استعلام Vector وعوامل تصفية استعلام نص
  • التصنيف الدلالي وملفات تعريف تسجيل النقاط لتعزيز الصلة
  • الإكمال التلقائي مصطلحات البحث المكتوبة جزئيا استنادا إلى المستندات الموجودة في الفهرس
  • اقتراح النص الأكثر احتمالا للمطابقة في المستندات لأنواع المستخدمين
  • إضافة المستندات أو تحديثها أو حذفها المستندات من فهرس

• يسمح لك SearchIndexClient ب:

  • إنشاء فهرس بحث أو حذفه أو تحديثه أو تكوينه
  • تعريف تعيينات المرادفات المخصصة لتوسيع الاستعلامات أو إعادة كتابتها

• يسمح لك SearchIndexerClient ب:

  • بدء المفهرسات لتتبع ارتباطات مصادر البيانات تلقائيا
  • تعريف مجموعات المهارات التي تعمل بالطاقة الذكاء الاصطناعي لتحويل بياناتك وإثرائها

ملاحظة: لا يمكن لهؤلاء العملاء العمل في المستعرض لأن واجهات برمجة التطبيقات التي يستدعيها لا تدعم مشاركة الموارد عبر المنشأ (CORS).

مفاهيم محددة TypeScript/JavaScript

الوثائق

عنصر مخزن داخل فهرس بحث. يتم وصف شكل هذا المستند في الفهرس باستخدام الخاصية fields. كل SearchField له اسم، نوع بيانات، وبيانات تعريف إضافية مثل ما إذا كان قابلا للبحث أو التصفية.

تقسيم

عادة ما ترغب في إظهار مجموعة فرعية من نتائج البحث للمستخدم في وقت واحد. لدعم ذلك، يمكنك استخدام المعلمات topskipincludeTotalCount لتوفير تجربة صفحة أعلى نتائج البحث.

ترميز حقل المستند

يتم تعيين أنواع البيانات المدعومة في فهرس إلى أنواع JSON في طلبات/استجابات واجهة برمجة التطبيقات. تحتفظ مكتبة عميل JS بهذه في الغالب كما هي، مع بعض الاستثناءات:

• يتم تحويل Edm.DateTimeOffset إلى DateJS .
• يتم تحويل Edm.GeographyPoint إلى نوع GeographyPoint تم تصديره بواسطة مكتبة العميل.
• يتم تسلسل القيم الخاصة لنوع number (NaN، Infinity، -Infinity) كسلاسل في واجهة برمجة تطبيقات REST، ولكن يتم تحويلها مرة أخرى إلى number بواسطة مكتبة العميل.

ملاحظة: يتم تحويل أنواع البيانات استنادا إلى القيمة، وليس نوع الحقل في مخطط الفهرس. وهذا يعني أنه إذا كان لديك سلسلة تاريخ ISO8601 (على سبيل المثال، "2020-03-06T18:48:27.896Z") كقيمة لحقل، تحويلها إلى تاريخ بغض النظر عن كيفية تخزينها في المخطط.

امثله

توضح الأمثلة التالية الأساسيات - يرجى تحقق من عيناتنا لأكثر من ذلك بكثير.

• إنشاء فهرس
• استرداد مستند معين من الفهرس
• إضافة مستندات إلى الفهرس
• إجراء بحث على المستندات
  • الاستعلام باستخدام TypeScript
  • الاستعلام باستخدام عوامل تصفية OData
  • الاستعلام باستخدام الواجهات

إنشاء فهرس

const { SearchIndexClient, AzureKeyCredential } = require("@azure/search-documents");

const client = new SearchIndexClient("<endpoint>", new AzureKeyCredential("<apiKey>"));

async function main() {
  const result = await client.createIndex({
    name: "example-index",
    fields: [
      {
        type: "Edm.String",
        name: "id",
        key: true,
      },
      {
        type: "Edm.Double",
        name: "awesomenessLevel",
        sortable: true,
        filterable: true,
        facetable: true,
      },
      {
        type: "Edm.String",
        name: "description",
        searchable: true,
      },
      {
        type: "Edm.ComplexType",
        name: "details",
        fields: [
          {
            type: "Collection(Edm.String)",
            name: "tags",
            searchable: true,
          },
        ],
      },
      {
        type: "Edm.Int32",
        name: "hiddenWeight",
        hidden: true,
      },
    ],
  });

  console.log(result);
}

main();

استرداد مستند معين من فهرس

يمكن استرداد مستند معين بقيمة المفتاح الأساسي الخاصة به:

const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");

const client = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));

async function main() {
  const result = await client.getDocument("1234");
  console.log(result);
}

main();

إضافة مستندات إلى فهرس

يمكنك تحميل مستندات متعددة إلى فهرس داخل دفعة:

const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");

const client = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));

async function main() {
  const uploadResult = await client.uploadDocuments([
    // JSON objects matching the shape of the client's index
    {},
    {},
    {},
  ]);
  for (const result of uploadResult.results) {
    console.log(`Uploaded ${result.key}; succeeded? ${result.succeeded}`);
  }
}

main();

إجراء بحث على المستندات

لسرد كافة نتائج استعلام معين، يمكنك استخدام search مع سلسلة بحث تستخدم بناء جملة استعلام بسيط:

const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");

const client = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));

async function main() {
  const searchResults = await client.search("wifi -luxury");
  for await (const result of searchResults.results) {
    console.log(result);
  }
}

main();

للبحث الأكثر تقدما الذي يستخدم بناء جملة Lucene، حدد queryType ليكون full:

const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");

const client = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));

async function main() {
  const searchResults = await client.search('Category:budget AND "recently renovated"^3', {
    queryType: "full",
    searchMode: "all",
  });
  for await (const result of searchResults.results) {
    console.log(result);
  }
}

main();

الاستعلام باستخدام TypeScript

في TypeScript، يأخذ SearchClient معلمة عامة هي شكل نموذج مستندات الفهرس. يسمح لك هذا بإجراء بحث مكتوب بقوة عن الحقول التي تم إرجاعها في النتائج. يمكن ل TypeScript أيضا التحقق من الحقول التي يتم إرجاعها عند تحديد معلمة select.

import { SearchClient, AzureKeyCredential, SelectFields } from "@azure/search-documents";

// An example schema for documents in the index
interface Hotel {
  hotelId?: string;
  hotelName?: string | null;
  description?: string | null;
  descriptionVector?: Array<number>;
  parkingIncluded?: boolean | null;
  lastRenovationDate?: Date | null;
  rating?: number | null;
  rooms?: Array<{
    beds?: number | null;
    description?: string | null;
  }>;
}

const client = new SearchClient<Hotel>(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<apiKey>")
);

async function main() {
  const searchResults = await client.search("wifi -luxury", {
    // Only fields in Hotel can be added to this array.
    // TS will complain if one is misspelled.
    select: ["hotelId", "hotelName", "rooms/beds"],
  });

  // These are other ways to declare the correct type for `select`.
  const select = ["hotelId", "hotelName", "rooms/beds"] as const;
  // This declaration lets you opt out of narrowing the TypeScript type of your documents,
  // though the AI Search service will still only return these fields.
  const selectWide: SelectFields<Hotel>[] = ["hotelId", "hotelName", "rooms/beds"];
  // This is an invalid declaration. Passing this to `select` will result in a compiler error
  // unless you opt out of including the model in the client constructor.
  const selectInvalid = ["hotelId", "hotelName", "rooms/beds"];

  for await (const result of searchResults.results) {
    // result.document has hotelId, hotelName, and rating.
    // Trying to access result.document.description would emit a TS error.
    console.log(result.document.hotelName);
  }
}

main();

الاستعلام باستخدام عوامل تصفية OData

يسمح لك استخدام معلمة الاستعلام filter بالاستعلام عن فهرس باستخدام بناء جملة تعبير $filter OData .

const { SearchClient, AzureKeyCredential, odata } = require("@azure/search-documents");

const client = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));

async function main() {
  const baseRateMax = 200;
  const ratingMin = 4;
  const searchResults = await client.search("WiFi", {
    filter: odata`Rooms/any(room: room/BaseRate lt ${baseRateMax}) and Rating ge ${ratingMin}`,
    orderBy: ["Rating desc"],
    select: ["hotelId", "hotelName", "Rating"],
  });
  for await (const result of searchResults.results) {
    // Each result will have "HotelId", "HotelName", and "Rating"
    // in addition to the standard search result property "score"
    console.log(result);
  }
}

main();

الاستعلام باستخدام المتجهات

يمكن الاستعلام عن تضمينات النص باستخدام معلمة البحث vector. راجع الاستعلام المتجهات واستعلامات عامل التصفية لمزيد من المعلومات.

const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");

const searchClient = new SearchClient(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<apiKey>")
);

async function main() {
  const queryVector = [...];
  const searchResults = await searchClient.search("*", {
    vectorSearchOptions: {
      queries: [
        {
          kind: "vector",
          vector: queryVector,
          fields: ["descriptionVector"],
          kNearestNeighborsCount: 3,
        },
      ],
    },
  });
  for await (const result of searchResults.results) {
    // These results are the nearest neighbors to the query vector
    console.log(result);
  }
}

main();

الاستعلام باستخدام الواجهات

يتم استخدام الواجهات لمساعدة مستخدم تطبيقك على تحسين البحث على طول الأبعاد التي تم تكوينها مسبقا. يوفر بناء جملة Facet خيارات لفرز قيم واجهة المستودع وفرزها.

const { SearchClient, AzureKeyCredential } = require("@azure/search-documents");

const client = new SearchClient("<endpoint>", "<indexName>", new AzureKeyCredential("<apiKey>"));

async function main() {
  const searchResults = await client.search("WiFi", {
    facets: ["category,count:3,sort:count", "rooms/baseRate,interval:100"],
  });
  console.log(searchResults.facets);
  // Output will look like:
  // {
  //   'rooms/baseRate': [
  //     { count: 16, value: 0 },
  //     { count: 17, value: 100 },
  //     { count: 17, value: 200 }
  //   ],
  //   category: [
  //     { count: 5, value: 'Budget' },
  //     { count: 5, value: 'Luxury' },
  //     { count: 5, value: 'Resort and Spa' }
  //   ]
  // }
}

main();

عند استرداد النتائج، ستتوفر خاصية facets تشير إلى عدد النتائج التي تقع في كل مستودع واجهة. يمكن استخدام هذا لتحسين (على سبيل المثال، إصدار بحث متابعة يقوم بتصفية Rating أكبر من أو يساوي 3 وأقل من 4.)

استكشاف الاخطاء

تسجيل

يمكن أن يساعد تمكين التسجيل في الكشف عن معلومات مفيدة حول حالات الفشل. لمشاهدة سجل طلبات واستجابات HTTP، قم بتعيين متغير البيئة AZURE_LOG_LEVEL إلى info. بدلا من ذلك، يمكن تمكين التسجيل في وقت التشغيل عن طريق استدعاء setLogLevel في @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

للحصول على إرشادات أكثر تفصيلا حول كيفية تمكين السجلات، يمكنك إلقاء نظرة على مستندات حزمة @azure/المسجل.

الخطوات التالية

• الذهاب إلى أبعد من ذلك مع مستندات البحث وعيناتنا
• اقرأ المزيد حول خدمة Azure الذكاء الاصطناعي Search

المساهمه

إذا كنت ترغب في المساهمة في هذه المكتبة، فيرجى قراءة دليل المساهمة لمعرفة المزيد حول كيفية إنشاء التعليمات البرمجية واختبارها.

يرحب هذا المشروع بالمساهمات والاقتراحات. تتطلب معظم المساهمات منك الموافقة على اتفاقية ترخيص المساهمين (CLA) التي تعلن أن لديك الحق في منحنا حقوق استخدام مساهمتك. لمزيد من التفاصيل، تفضل بزيارة cla.microsoft.com.

اعتمد هذا المشروع قواعد السلوك مفتوحة المصدر من Microsoft. لمزيد من المعلومات، راجع الأسئلة المتداولة حول قواعد السلوك أو الاتصال opencode@microsoft.com مع أي أسئلة أو تعليقات إضافية.

المشاريع ذات الصلة

• Microsoft Azure SDK ل JavaScript

مرات الظهور