البحث باستخدام الذكاء الاصطناعي في Azure client library for JavaScript - الإصدار 13.0.0

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

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

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

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

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

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

الشروع

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

npm install @azure/search-documents

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

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

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

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

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

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

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

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

بدلا من ذلك، يمكنك استخدام أمر Azure CLI التالي لاسترداد مفتاح واجهة برمجة التطبيقات من خدمة البحث:

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

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

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

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

import {
  SearchClient,
  AzureKeyCredential,
  SearchIndexClient,
  SearchIndexerClient,
} from "@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
import {
  SearchClient,
  AzureKeyCredential,
  KnownSearchAudience,
  SearchIndexClient,
  SearchIndexerClient,
} from "@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 تعرض مكتبة العميل العمليات على هذه الموارد من خلال ثلاثة أنواع رئيسية من العملاء.

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

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

الوثائق

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

تقسيم

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

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

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

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

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

امثله

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

إنشاء فهرس

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

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

const result = await indexClient.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(`Index created with name ${result.name}`);

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

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

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

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

const result = await searchClient.getDocument("1234");

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

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

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

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

const uploadResult = await searchClient.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}`);
}

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

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

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

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

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

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

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

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

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

الاستعلام باستخدام 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 searchClient = new SearchClient<Hotel>(
  "<endpoint>",
  "<indexName>",
  new AzureKeyCredential("<apiKey>"),
);

const searchResults = await searchClient.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);
}

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

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

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

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

const baseRateMax = 200;
const ratingMin = 4;
const searchResults = await searchClient.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);
}

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

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

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

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

const queryVector: number[] = [
  // Embedding of the query "What are the most luxurious hotels?"
];
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);
}

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

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

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

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

const searchResults = await searchClient.search("WiFi", {
  facets: ["category,count:3,sort:count", "rooms/baseRate,interval:100"],
});
console.log(searchResults.facets);

عند استرداد النتائج، 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 مع أي أسئلة أو تعليقات إضافية.

  • Last updated on