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

  • مقالة

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

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

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

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

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

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

الشروع في العمل

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

npm install @azure/search-documents

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

راجع سياسة الدعم الخاصة بنا لمزيد من التفاصيل.

المتطلبات الأساسية

لإنشاء خدمة بحث جديدة، يمكنك استخدام مدخل Microsoft 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 أو مفتاح API. يمكنك الرجوع إلى الوثائق لمزيد من المعلومات حول نهج المصادقة المدعومة باستخدام خدمة البحث.

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

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

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

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

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

بمجرد أن يكون لديك مفتاح 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>"));

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

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

  • تعيين في AudienceSearchClientOptions
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 على فهرس واحد أو أكثر يوفر تخزينا مستمرا للبيانات القابلة للبحث في شكل مستندات JSON. (إذا كنت جديدا على البحث، يمكنك إجراء قياس تقريبي جدا بين الفهارس وجداول قاعدة البيانات.)@azure/search-documents تعرض مكتبة العميل العمليات على هذه الموارد من خلال ثلاثة أنواع عميل رئيسية.

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

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

المستندات

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

ترقيم الصفحات

عادة ما ترغب فقط في عرض مجموعة فرعية من نتائج البحث للمستخدم في وقت واحد. لدعم ذلك، يمكنك استخدام topالمعلمات و skipincludeTotalCount لتوفير تجربة مصفحة أعلى نتائج البحث.

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

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

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

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

أمثلة

توضح الأمثلة التالية الأساسيات - يرجى الاطلاع على عيناتنا لمزيد من المعلومات.

إنشاء فهرس

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> | null;
  parkingIncluded?: boolean | null;
  lastRenovationDate?: Date | null;
  rating?: number | null;
  rooms?: Array<{
    beds?: number | null;
    description?: string | null;
  } | 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 الاستعلام بالاستعلام عن فهرس باستخدام بناء جملة تعبير OData $filter.

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, odata } = require("@azure/search-documents");

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

async function main() {
  const queryVector = [...]
  const searchResults = await searchClient.search("*", {
    vector: {
      fields: ["descriptionVector"],
      kNearestNeighborsCount: 3,
      value: queryVector,
    },
  });
  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/المسجل.

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

المساهمة

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

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

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

مرات الظهور