التشغيل السريع: بحث المتجهات

في هذه البداية السريعة، تستخدم مكتبة العملاء Azure AI Search ل .NET لإنشاء وتحميل واستعلام <فهرس متجه c1>vector. توفر مكتبة عملاء .NET تجريدا على واجهات برمجة تطبيقات REST لعمليات الفهرس.

في Azure AI Search، يحتوي مؤشر المتجهات على مخطط فهرس يحدد الحقول المتجهية وغير المتجهية، وتكوين بحث متجهات للخوارزميات التي تنشئ مساحة التضمين، وإعدادات على تعريفات الحقول المتجهية التي يتم تقييمها عند وقت الاستعلام. الفهارس - إنشاء أو تحديث (REST API) ينشئ فهرس المتجه.

تلميح

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

تكوين الوصول

قبل أن تبدأ، تأكد من أن لديك صلاحيات للوصول إلى المحتوى والعمليات في Azure AI Search. يستخدم هذا البدء السريع معرف Microsoft Entra ID للمصادقة والوصول القائم على الأدوار للتفويض. يجب أن تكون Owner أو User Access Administrator لتعيين الأدوار. إذا لم تكن الأدوار ممكنة، فاستخدم المصادقة المستندة إلى المفتاح بدلا من ذلك.

لتكوين الوصول الموصى به المستند إلى الدور:

  1. فعل access المعتمدة على الأدوار search service.

  2. قم بتعيين الأدوار التالية لحساب المستخدم الخاص بك.

    • Search Service المساهم

    • مساهم بيانات فهرس البحث

    • قارئ بيانات فهرس البحث

الحصول على نقطة النهاية

كل خدمة Azure AI Search لديها endpoint، وهو رابط فريد يحدد ويوفر الوصول إلى الشبكة للخدمة. في قسم لاحق، تحدد هذه النقطة النهائية للاتصال بخدمة البحث الخاصة بك بشكل برمجي.

للحصول على نقطة النهاية:

  1. انتقل إلى خدمة البحث في مدخل Microsoft Azure.

  2. من الجزء الأيمن، حدد نظرة عامة.

  3. دون نقطة النهاية، والتي يجب أن تبدو https://my-service.search.windows.net.

إعداد البيئة

  1. استخدم Git لاستنساخ مستودع العينات.

    git clone https://github.com/Azure-Samples/azure-search-dotnet-samples

  2. انتقل إلى مجلد البدء السريع.

    cd azure-search-dotnet-samples/quickstart-vector-search

  3. في VectorSearchCreatePopulateIndex/appsettings.json، استبدل قيمة البديل المؤقت ل Endpoint بعنوان URL الذي حصلت عليه في Get endpoint.

  4. كرر الخطوة السابقة ل VectorSearchExamples/appsettings.json.

  5. للمصادقة بدون مفتاح باستخدام Microsoft Entra ID، سجل الدخول إلى حسابك في Azure. إذا كان لديك عدة اشتراكات، اختر الاشتراك الذي يحتوي على خدمة Azure AI Search الخاصة بك.

    az login

تشغيل التعليمات البرمجية

  1. شغل أول مشروع لإنشاء وملء الفهرس.

    cd VectorSearchCreatePopulateIndex
dotnet run

  2. في VectorSearchExamples/Program.cs، قم بإلغاء التعليق على طرق الاستعلام التي تريد تشغيلها.

  3. شغل المشروع الثاني لتنفيذ تلك الاستعلامات على الفهرس.

    cd ..\VectorSearchExamples
dotnet run

الاخراج

تشمل نتائج المشروع الأول تأكيد إنشاء الفهرس ورفع المستندات بنجاح.

Creating or updating index 'hotels-vector-quickstart'...
Index 'hotels-vector-quickstart' updated.

Key: 1, Succeeded: True
Key: 2, Succeeded: True
Key: 3, Succeeded: True
Key: 4, Succeeded: True
Key: 48, Succeeded: True
Key: 49, Succeeded: True
Key: 13, Succeeded: True

يظهر مخرجات المشروع الثاني نتائج البحث لكل طريقة استعلام مفعلة. المثال التالي يعرض نتائج البحث باتجاه الاتجاه الواحد.

Single Vector Search Results:
Score: 0.6605852, HotelId: 48, HotelName: Nordick's Valley Motel
Score: 0.6333684, HotelId: 13, HotelName: Luxury Lion Resort
Score: 0.605672, HotelId: 4, HotelName: Sublime Palace Hotel
Score: 0.6026341, HotelId: 49, HotelName: Swirling Currents Hotel
Score: 0.57902366, HotelId: 2, HotelName: Old Century Hotel

فهم الكود

ملاحظة

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

الآن بعد أن قمت بتشغيل التعليمات البرمجية ، دعنا نقسم الخطوات الرئيسية:

  1. إنشاء فهرس متجه
  2. تحميل المستندات إلى الفهرس
  3. استعلام الفهرس

إنشاء فهرس متجه

قبل أن تضيف المحتوى إلى Azure AI Search، يجب عليك إنشاء فهرس لتحديد كيفية تخزين وهيكلة المحتوى.

مخطط الفهرس منظم حول محتوى الفنادق. تتكون بيانات العينة من أوصاف متجهة وغير عاملة للفنادق الوهمية. الكود التالي في VectorSearchCreatePopulateIndex/Program.cs ينشئ مخطط الفهرس، بما في ذلك حقل DescriptionVectorالمتجهات .

static async Task CreateSearchIndex(string indexName, SearchIndexClient indexClient)
{
    var addressField = new ComplexField("Address");
    addressField.Fields.Add(new SearchableField("StreetAddress") { AnalyzerName = LexicalAnalyzerName.EnMicrosoft });
    addressField.Fields.Add(new SearchableField("City") { AnalyzerName = LexicalAnalyzerName.EnMicrosoft, IsFacetable = true, IsFilterable = true });
    addressField.Fields.Add(new SearchableField("StateProvince") { AnalyzerName = LexicalAnalyzerName.EnMicrosoft, IsFacetable = true, IsFilterable = true });
    addressField.Fields.Add(new SearchableField("PostalCode") { AnalyzerName = LexicalAnalyzerName.EnMicrosoft, IsFacetable = true, IsFilterable = true });
    addressField.Fields.Add(new SearchableField("Country") { AnalyzerName = LexicalAnalyzerName.EnMicrosoft, IsFacetable = true, IsFilterable = true });

    var allFields = new List<SearchField>()
    {
        new SimpleField("HotelId", SearchFieldDataType.String) { IsKey = true, IsFacetable = true, IsFilterable = true },
        new SearchableField("HotelName") { AnalyzerName = LexicalAnalyzerName.EnMicrosoft },
        new SearchableField("Description") { AnalyzerName = LexicalAnalyzerName.EnMicrosoft },
        new VectorSearchField("DescriptionVector", 1536, "my-vector-profile"),
        new SearchableField("Category") { AnalyzerName = LexicalAnalyzerName.EnMicrosoft, IsFacetable = true, IsFilterable = true },
        new SearchableField("Tags", collection: true) { AnalyzerName = LexicalAnalyzerName.EnMicrosoft, IsFacetable = true, IsFilterable = true },
        new SimpleField("ParkingIncluded", SearchFieldDataType.Boolean) { IsFacetable = true, IsFilterable = true },
        new SimpleField("LastRenovationDate", SearchFieldDataType.DateTimeOffset) { IsSortable = true },
        new SimpleField("Rating", SearchFieldDataType.Double) { IsFacetable = true, IsFilterable = true, IsSortable = true },
        addressField,
        new SimpleField("Location", SearchFieldDataType.GeographyPoint) { IsFilterable = true, IsSortable = true },
    };

    // Create the suggester configuration
    var suggester = new SearchSuggester("sg", new[] { "Address/City", "Address/Country" });

    // Create the semantic search
    var semanticSearch = new SemanticSearch()
    {
        Configurations =
        {
            new SemanticConfiguration(
                name: "semantic-config",
                prioritizedFields: new SemanticPrioritizedFields
                {
                    TitleField = new SemanticField("HotelName"),
                    KeywordsFields = { new SemanticField("Category") },
                    ContentFields = { new SemanticField("Description") }
                })
        }
    };

    // Add vector search configuration
    var vectorSearch = new VectorSearch();
    vectorSearch.Algorithms.Add(new HnswAlgorithmConfiguration(name: "my-hnsw-vector-config-1"));
    vectorSearch.Profiles.Add(new VectorSearchProfile(name: "my-vector-profile", algorithmConfigurationName: "my-hnsw-vector-config-1"));

    var definition = new SearchIndex(indexName)
    {
        Fields = allFields,
        Suggesters = { suggester },
        VectorSearch = vectorSearch,
        SemanticSearch = semanticSearch
    };

    // Create or update the index
    Console.WriteLine($"Creating or updating index '{indexName}'...");
    var result = await indexClient.CreateOrUpdateIndexAsync(definition);
    Console.WriteLine($"Index '{result.Value.Name}' updated.");
    Console.WriteLine();
}

المسارات الرئيسية:

  • يمكنك تعريف فهرس عن طريق إنشاء قائمة حقول.

  • يدعم هذا الفهرس تحديدا قدرات بحث متعددة:

  • المعامل الثاني في VectorSearchField يحدد vectorSearchDimensions، والذي يجب أن يطابق حجم مخرجات نموذج التضمين الخاص بك. يستخدم هذا البدء السريع 1,536 بعدا ليتناسب مع النموذج text-embedding-ada-002 .

  • يحدد هذا VectorSearch التكوين خوارزمية أقرب جار تقريبي (ANN). تشمل الخوارزميات المدعومة العالم الصغير القابل للملاحة الهرمي (HNSW) والجار الشامل K-أقرب جار (KNN). لمزيد من المعلومات، راجع الصلة في البحث المتجه.

تحميل المستندات إلى الفهرس

الفهارس التي تم إنشاؤها حديثا فارغة. لتعبئة فهرس وجعله قابلا للبحث، يجب تحميل مستندات JSON التي تتوافق مع مخطط الفهرس.

في Azure AI Search، تعمل المستندات كمدخلات للفهرسة ومخرجات للاستعلامات. للتبسيط، يوفر هذا البدء السريع نماذج من مستندات الفنادق مع متجهات محسوبة مسبقا. في سيناريوهات الإنتاج، غالبا ما يتم سحب المحتوى من مصادر بيانات متصلة وتحويله إلى JSON باستخدام الفهارس.

الرمز التالي يرفع المستندات إلى HotelData.json خدمة البحث الخاصة بك.

static async Task UploadDocs(SearchClient searchClient)
{
    var jsonPath = Path.Combine(Directory.GetCurrentDirectory(), "HotelData.json");

    // Read and parse hotel data
    var json = await File.ReadAllTextAsync(jsonPath);
    List<Hotel> hotels = new List<Hotel>();
    try
    {
        using var doc = JsonDocument.Parse(json);
        if (doc.RootElement.ValueKind != JsonValueKind.Array)
        {
            Console.WriteLine("HotelData.json root is not a JSON array.");
        }
        // Deserialize all hotel objects
        hotels = doc.RootElement.EnumerateArray()
            .Select(e => JsonSerializer.Deserialize<Hotel>(e.GetRawText()))
            .Where(h => h != null)
            .ToList();
    }
    catch (JsonException ex)
    {
        Console.WriteLine($"Failed to parse HotelData.json: {ex.Message}");
    }

    try
    {
        // Upload hotel documents to Azure Search
        var result = await searchClient.UploadDocumentsAsync(hotels);
        foreach (var r in result.Value.Results)
        {
            Console.WriteLine($"Key: {r.Key}, Succeeded: {r.Succeeded}");
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine("Failed to upload documents: " + ex);
    }
}

يتفاعل كودك مع فهرس بحث محدد مستضاف في خدمة Azure AI Search الخاصة بك من خلال SearchClient، وهو الكائن الرئيسي الذي توفره حزمة Azure.Search.Documents. يوفر الوصول SearchClient إلى عمليات الفهرس، مثل:

  • استيعاب البيانات: UploadDocuments(), MergeDocuments(), DeleteDocuments()

  • عمليات البحث: Search(), Autocomplete(), Suggest()

استعلام الفهرس

تظهر الاستعلامات أنماط VectorSearchExamples بحث مختلفة. تستند استعلامات المتجهات النموذجية إلى سلسلتين:

  • سلسلة بحث كاملة النص: "historic hotel walk to restaurants and shopping"

  • سلسلة استعلام المتجه: "quintessential lodging near running trails, eateries, retail" (موجهة إلى تمثيل رياضي)

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

تبدأ الأمثلة التالية باستعلام متجه أساسي وتضيف تدريجيا فلاتر، وبحث في الكلمات المفتاحية، وإعادة ترتيب دلالي.

توضح الطريقة SearchSingleVector سيناريو أساسي حيث تريد العثور على أوصاف مستندات تتطابق بشكل وثيق مع سلسلة استعلام المتجه. VectorizedQuery تكوين البحث المتجه:

  • KNearestNeighborsCount يحد من عدد النتائج التي يتم إرجاعها بناء على تشابه المتجهات.
  • Fields يحدد الحقل المتجه الذي يجب البحث ضده.
public static async Task SearchSingleVector(SearchClient searchClient, ReadOnlyMemory<float> precalculatedVector)
{
    SearchResults<Hotel> response = await searchClient.SearchAsync<Hotel>(
        new SearchOptions
        {
            VectorSearch = new()
            {
                Queries = { new VectorizedQuery(precalculatedVector) { KNearestNeighborsCount = 5, Fields = { "DescriptionVector" } } }
            },
            Select = { "HotelId", "HotelName", "Description", "Category", "Tags" },
        });

    Console.WriteLine($"Single Vector Search Results:");
    await foreach (SearchResult<Hotel> result in response.GetResultsAsync())
    {
        Hotel doc = result.Document;
        Console.WriteLine($"Score: {result.Score}, HotelId: {doc.HotelId}, HotelName: {doc.HotelName}");
    }
    Console.WriteLine();
}

البحث باتجاه واحد باستخدام مرشح

في Azure AI Search، ينطبق filters على الحقول غير المتجهية في الفهرس. تقوم الطريقة SearchSingleVectorWithFilter بتصفية الساحة Tags لتصفية أي فنادق لا توفر واي فاي مجاني.

public static async Task SearchSingleVectorWithFilter(SearchClient searchClient, ReadOnlyMemory<float> precalculatedVector)
{
    SearchResults<Hotel> responseWithFilter = await searchClient.SearchAsync<Hotel>(
        new SearchOptions
        {
            VectorSearch = new()
            {
                Queries = { new VectorizedQuery(precalculatedVector) { KNearestNeighborsCount = 5, Fields = { "DescriptionVector" } } }
            },
            Filter = "Tags/any(tag: tag eq 'free wifi')",
            Select = { "HotelId", "HotelName", "Description", "Category", "Tags" }
        });

    Console.WriteLine($"Single Vector Search With Filter Results:");
    await foreach (SearchResult<Hotel> result in responseWithFilter.GetResultsAsync())
    {
        Hotel doc = result.Document;
        Console.WriteLine($"Score: {result.Score}, HotelId: {doc.HotelId}, HotelName: {doc.HotelName}, Tags: {string.Join(String.Empty, doc.Tags)}");
    }
    Console.WriteLine();
}

البحث باتجاه واحد باستخدام مرشح جغرافي

يمكنك تحديد مرشح جغرافي مكاني لتقييد النتائج بمنطقة جغرافية محددة. تحدد الطريقة SingleSearchWithGeoFilter نقطة جغرافية (واشنطن العاصمة، باستخدام إحداثيات خطوط الطول والعرض) وتعيد الفنادق ضمن 300 كيلومتر. افتراضيا، تعمل الفلاتر بعد البحث المتجه.

public static async Task SingleSearchWithGeoFilter(SearchClient searchClient, ReadOnlyMemory<float> precalculatedVector)
{
    SearchResults<Hotel> responseWithGeoFilter = await searchClient.SearchAsync<Hotel>(
        new SearchOptions
        {
            VectorSearch = new()
            {
                Queries = { new VectorizedQuery(precalculatedVector) { KNearestNeighborsCount = 5, Fields = { "DescriptionVector" } } }
            },
            Filter = "geo.distance(Location, geography'POINT(-77.03241 38.90166)') le 300",
            Select = { "HotelId", "HotelName", "Description", "Address", "Category", "Tags" },
            Facets = { "Address/StateProvince" },
        });

    Console.WriteLine($"Vector query with a geo filter:");
    await foreach (SearchResult<Hotel> result in responseWithGeoFilter.GetResultsAsync())
    {
        Hotel doc = result.Document;
        Console.WriteLine($"HotelId: {doc.HotelId}");
        Console.WriteLine($"HotelName: {doc.HotelName}");
        Console.WriteLine($"Score: {result.Score}");
        Console.WriteLine($"City/State: {doc.Address.City}/{doc.Address.StateProvince}");
        Console.WriteLine($"Description: {doc.Description}");
        Console.WriteLine();
    }
    Console.WriteLine();
}

يجمع البحث الهجين بين استعلامات النص الكامل والاستعلامات المتجهية في طلب واحد. تقوم الطريقة SearchHybridVectorAndText بتشغيل كلا نوعي الاستعلام في نفس الوقت، ثم تستخدم دمج الترتيب المتبادل (RRF) لدمج النتائج في تصنيف موحد. يستخدم RRF عكس ترتيب النتائج من كل مجموعة نتائج لإنتاج تصنيف مدمج. لاحظ أن درجات البحث الهجين أصغر بشكل موحد من درجات الاستعلام الفردي.

public static async Task<SearchResults<Hotel>> SearchHybridVectorAndText(SearchClient searchClient, ReadOnlyMemory<float> precalculatedVector)
{
    SearchResults<Hotel> responseWithFilter = await searchClient.SearchAsync<Hotel>(
        "historic hotel walk to restaurants and shopping",
        new SearchOptions
        {
            VectorSearch = new()
            {
                Queries = { new VectorizedQuery(precalculatedVector) { KNearestNeighborsCount = 5, Fields = { "DescriptionVector" } } }
            },
            Select = { "HotelId", "HotelName", "Description", "Category", "Tags" },
            Size = 5,
        });

    Console.WriteLine($"Hybrid search results:");
    await foreach (SearchResult<Hotel> result in responseWithFilter.GetResultsAsync())
    {
        Hotel doc = result.Document;
        Console.WriteLine($"Score: {result.Score}");
        Console.WriteLine($"HotelId: {doc.HotelId}");
        Console.WriteLine($"HotelName: {doc.HotelName}");
        Console.WriteLine($"Description: {doc.Description}");
        Console.WriteLine($"Category: {doc.Category}");
        Console.WriteLine($"Tags: {string.Join(String.Empty, doc.Tags)}");
        Console.WriteLine();
    }
    Console.WriteLine();
    return responseWithFilter;
}

تظهر الطريقة SearchHybridVectorAndSemanticالتصنيف الدلالي، الذي يعيد ترتيب النتائج بناء على فهم اللغة.

public static async Task SearchHybridVectorAndSemantic(SearchClient searchClient, ReadOnlyMemory<float> precalculatedVector)
{
    SearchResults<Hotel> responseWithFilter = await searchClient.SearchAsync<Hotel>(
        "historic hotel walk to restaurants and shopping",
        new SearchOptions
        {
            IncludeTotalCount = true,
            VectorSearch = new()
            {
                Queries = { new VectorizedQuery(precalculatedVector) { KNearestNeighborsCount = 5, Fields = { "DescriptionVector" } } }
            },
            Select = { "HotelId", "HotelName", "Description", "Category", "Tags" },
            SemanticSearch = new SemanticSearchOptions
            {
                SemanticConfigurationName = "semantic-config"
            },
            QueryType = SearchQueryType.Semantic,
            Size = 5
        });

    Console.WriteLine($"Hybrid search results:");
    await foreach (SearchResult<Hotel> result in responseWithFilter.GetResultsAsync())
    {
        Hotel doc = result.Document;
        Console.WriteLine($"Score: {result.Score}");
        Console.WriteLine($"HotelId: {doc.HotelId}");
        Console.WriteLine($"HotelName: {doc.HotelName}");
        Console.WriteLine($"Description: {doc.Description}");
        Console.WriteLine($"Category: {doc.Category}");
        Console.WriteLine();
    }
    Console.WriteLine();
}

قارن هذه النتائج مع نتائج البحث الهجينة من الاستعلام السابق. بدون إعادة ترتيب دلالية، يحتل فندق سوبلايم بالاس المرتبة الأولى لأن دمج الترتيب المتبادل (RRF) يجمع بين درجات النص والمتجه لإنتاج نتيجة مدمجة. بعد إعادة ترتيب دلالية، ينتقل فندق Swirling Currents إلى الصدارة.

يستخدم المصنف الدلالي نماذج فهم الآلة لتقييم مدى توافق كل نتيجة مع نية الاستعلام. وصف فندق التيارات الدوامة يذكر "walking access to shopping, dining, entertainment and the city center"، وهذا يتوافق بشكل وثيق مع استعلام "walk to restaurants and shopping"البحث . هذا التوافق الدلالي في تناول الطعام والتسوق القريب يرفعه فوق فندق سوبلايم بالاس، الذي لا يركز على المرافق القابلة للمشي في وصفه.

المسارات الرئيسية:

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

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

تنظيف الموارد

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

في بوابة Azure، اختر All resources أو Resource groups من اللوحة اليسرى للعثور على الموارد وإدارتها. يمكنك حذف الموارد بشكل فردي أو حذف مجموعة الموارد لإزالة كل الموارد دفعة واحدة.

في هذه البداية السريعة، تستخدم مكتبة العملاء Azure AI Search ل Java لإنشاء وتحميل واستعلام <فهرس متجه c1>vector. توفر مكتبة عملاء Java تجريدا على واجهات برمجة تطبيقات REST لعمليات الفهرس.

في Azure AI Search، يحتوي مؤشر المتجهات على مخطط فهرس يحدد الحقول المتجهية وغير المتجهية، وتكوين بحث متجهات للخوارزميات التي تنشئ مساحة التضمين، وإعدادات على تعريفات الحقول المتجهية التي يتم تقييمها عند وقت الاستعلام. الفهارس - إنشاء أو تحديث (REST API) ينشئ فهرس المتجه.

تلميح

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

تكوين الوصول

قبل أن تبدأ، تأكد من أن لديك صلاحيات للوصول إلى المحتوى والعمليات في Azure AI Search. يستخدم هذا البدء السريع معرف Microsoft Entra ID للمصادقة والوصول القائم على الأدوار للتفويض. يجب أن تكون Owner أو User Access Administrator لتعيين الأدوار. إذا لم تكن الأدوار ممكنة، فاستخدم المصادقة المستندة إلى المفتاح بدلا من ذلك.

لتكوين الوصول الموصى به المستند إلى الدور:

  1. فعل access المعتمدة على الأدوار search service.

  2. قم بتعيين الأدوار التالية لحساب المستخدم الخاص بك.

    • Search Service المساهم

    • مساهم بيانات فهرس البحث

    • قارئ بيانات فهرس البحث

الحصول على نقطة النهاية

كل خدمة Azure AI Search لديها endpoint، وهو رابط فريد يحدد ويوفر الوصول إلى الشبكة للخدمة. في قسم لاحق، تحدد هذه النقطة النهائية للاتصال بخدمة البحث الخاصة بك بشكل برمجي.

للحصول على نقطة النهاية:

  1. انتقل إلى خدمة البحث في مدخل Microsoft Azure.

  2. من الجزء الأيمن، حدد نظرة عامة.

  3. دون نقطة النهاية، والتي يجب أن تبدو https://my-service.search.windows.net.

إعداد البيئة

  1. استخدم Git لاستنساخ مستودع العينات.

    git clone https://github.com/Azure-Samples/azure-search-java-samples

  2. انتقل إلى مجلد البدء السريع.

    cd azure-search-java-samples/quickstart-vector-search

  3. في src/main/resources/application.properties، استبدل قيمة البديل المؤقت ل azure.search.endpoint بعنوان URL الذي حصلت عليه في Get endpoint.

  4. ثبّت التبعيات.

    mvn clean dependency:copy-dependencies

    عندما يكتمل البناء، يجب أن ترى مجلد target/dependency في مجلد المشروع.

  5. للمصادقة بدون مفتاح باستخدام Microsoft Entra ID، سجل الدخول إلى حسابك في Azure. إذا كان لديك عدة اشتراكات، اختر الاشتراك الذي يحتوي على خدمة Azure AI Search الخاصة بك.

    az login

تشغيل التعليمات البرمجية

  1. أنشئ فهرس متجه.

    mvn compile exec:java "-Dexec.mainClass=com.example.search.CreateIndex"

  2. قم بتحميل المستندات التي تحتوي على تضمينات محسوبة مسبقا.

    mvn compile exec:java "-Dexec.mainClass=com.example.search.UploadDocuments"

  3. شغل استعلام بحث متجه.

    mvn compile exec:java "-Dexec.mainClass=com.example.search.SearchSingle"

  4. (اختياري) قم بتشغيل تنويعات إضافية للاستعلام.

    mvn compile exec:java "-Dexec.mainClass=com.example.search.SearchSingleWithFilter"
mvn compile exec:java "-Dexec.mainClass=com.example.search.SearchSingleWithFilterGeo"
mvn compile exec:java "-Dexec.mainClass=com.example.search.SearchHybrid"
mvn compile exec:java "-Dexec.mainClass=com.example.search.SearchSemanticHybrid"

الاخراج

يظهر مخرجات CreateIndex.java اسم الفهرس والتأكيد.

Using Azure Search endpoint: https://<search-service-name>.search.windows.net
Using Azure Search index: hotels-vector-quickstart
Creating index...
hotels-vector-quickstart created

يظهر الناتج حالة UploadDocuments.java النجاح لكل مستند مفهرس.

Uploading documents...
Key: 1, Succeeded: true, ErrorMessage: none
Key: 2, Succeeded: true, ErrorMessage: none
Key: 3, Succeeded: true, ErrorMessage: none
Key: 4, Succeeded: true, ErrorMessage: none
Key: 48, Succeeded: true, ErrorMessage: none
Key: 49, Succeeded: true, ErrorMessage: none
Key: 13, Succeeded: true, ErrorMessage: none
Waiting for indexing... Current count: 0
All documents indexed successfully.

يظهر الناتج SearchSingle.java نتائج البحث المتجهية المرتبة حسب درجة التشابه.

Single Vector search found 5
- HotelId: 48, HotelName: Nordick's Valley Motel, Tags: ["continental breakfast","air conditioning","free wifi"], Score 0.6605852
- HotelId: 13, HotelName: Luxury Lion Resort, Tags: ["bar","concierge","restaurant"], Score 0.6333684
- HotelId: 4, HotelName: Sublime Palace Hotel, Tags: ["concierge","view","air conditioning"], Score 0.605672
- HotelId: 49, HotelName: Swirling Currents Hotel, Tags: ["air conditioning","laundry service","24-hour front desk service"], Score 0.6026341
- HotelId: 2, HotelName: Old Century Hotel, Tags: ["pool","free wifi","air conditioning","concierge"], Score 0.57902366

فهم الكود

ملاحظة

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

الآن بعد أن قمت بتشغيل التعليمات البرمجية ، دعنا نقسم الخطوات الرئيسية:

  1. إنشاء فهرس متجه
  2. تحميل المستندات إلى الفهرس
  3. استعلام الفهرس

إنشاء فهرس متجه

قبل أن تضيف المحتوى إلى Azure AI Search، يجب عليك إنشاء فهرس لتحديد كيفية تخزين وهيكلة المحتوى.

مخطط الفهرس منظم حول محتوى الفنادق. تتكون بيانات العينة من أوصاف متجهة وغير عاملة للفنادق الوهمية. الكود التالي في CreateIndex.java ينشئ مخطط الفهرس، بما في ذلك حقل DescriptionVectorالمتجهات .

// Define fields
List<SearchField> fields = Arrays.asList(
    new SearchField("HotelId", SearchFieldDataType.STRING)
        .setKey(true)
        .setFilterable(true),
    new SearchField("HotelName", SearchFieldDataType.STRING)
        .setSortable(true)
        .setSearchable(true),
    new SearchField("Description", SearchFieldDataType.STRING)
        .setSearchable(true),
    new SearchField("DescriptionVector",
        SearchFieldDataType.collection(SearchFieldDataType.SINGLE))
        .setSearchable(true)
        .setVectorSearchDimensions(1536)
        .setVectorSearchProfileName("my-vector-profile"),
    new SearchField("Category", SearchFieldDataType.STRING)
        .setSortable(true)
        .setFilterable(true)
        .setFacetable(true)
        .setSearchable(true),
    new SearchField("Tags", SearchFieldDataType.collection(
        SearchFieldDataType.STRING))
        .setSearchable(true)
        .setFilterable(true)
        .setFacetable(true),
    // Additional fields: ParkingIncluded, LastRenovationDate, Rating, Address, Location
);

var searchIndex = new SearchIndex(indexName, fields);

// Define vector search configuration
var hnswParams = new HnswParameters()
    .setM(16)
    .setEfConstruction(200)
    .setEfSearch(128);
var hnsw = new HnswAlgorithmConfiguration("hnsw-vector-config");
hnsw.setParameters(hnswParams);

var vectorProfile = new VectorSearchProfile(
    "my-vector-profile",
    "hnsw-vector-config");
var vectorSearch = new VectorSearch()
    .setAlgorithms(Arrays.asList(hnsw))
    .setProfiles(Arrays.asList(vectorProfile));
searchIndex.setVectorSearch(vectorSearch);

// Define semantic configuration
var prioritizedFields = new SemanticPrioritizedFields()
    .setTitleField(new SemanticField("HotelName"))
    .setContentFields(Arrays.asList(new SemanticField("Description")))
    .setKeywordsFields(Arrays.asList(new SemanticField("Category")));
var semanticConfig = new SemanticConfiguration(
    "semantic-config",
    prioritizedFields);
var semanticSearch = new SemanticSearch()
    .setConfigurations(Arrays.asList(semanticConfig));
searchIndex.setSemanticSearch(semanticSearch);

// Define suggesters
var suggester = new SearchSuggester("sg", Arrays.asList("HotelName"));
searchIndex.setSuggesters(Arrays.asList(suggester));

// Create the search index
SearchIndex result = searchIndexClient.createOrUpdateIndex(searchIndex);

المسارات الرئيسية:

  • يمكنك تعريف فهرس عن طريق إنشاء قائمة حقول.

  • يدعم هذا الفهرس تحديدا قدرات بحث متعددة:

  • يجب أن تتطابق setVectorSearchDimensions() القيمة مع حجم مخرج نموذج التضمين الخاص بك. يستخدم هذا البدء السريع 1,536 بعدا ليتناسب مع النموذج text-embedding-ada-002 .

  • يحدد هذا VectorSearch التكوين خوارزمية أقرب جار تقريبي (ANN). تشمل الخوارزميات المدعومة العالم الصغير القابل للملاحة الهرمي (HNSW) والجار الشامل K-أقرب جار (KNN). لمزيد من المعلومات، راجع الصلة في البحث المتجه.

تحميل المستندات إلى الفهرس

الفهارس التي تم إنشاؤها حديثا فارغة. لتعبئة فهرس وجعله قابلا للبحث، يجب تحميل مستندات JSON التي تتوافق مع مخطط الفهرس.

في Azure AI Search، تعمل المستندات كمدخلات للفهرسة ومخرجات للاستعلامات. للتبسيط، يوفر هذا البدء السريع نماذج من مستندات الفنادق مع متجهات محسوبة مسبقا. في سيناريوهات الإنتاج، غالبا ما يتم سحب المحتوى من مصادر بيانات متصلة وتحويله إلى JSON باستخدام الفهارس.

الرمز التالي في UploadDocuments.java يرفع المستندات إلى خدمة البحث الخاصة بك.

// Documents contain hotel data with 1536-dimension vectors for DescriptionVector
static final List<Map<String, Object>> DOCUMENTS = Arrays.asList(
    new HashMap<>() {{
        put("@search.action", "mergeOrUpload");
        put("HotelId", "1");
        put("HotelName", "Stay-Kay City Hotel");
        put("Description", "This classic hotel is fully-refurbished...");
        put("DescriptionVector", Arrays.asList(/* 1536 float values */));
        put("Category", "Boutique");
        put("Tags", Arrays.asList("view", "air conditioning", "concierge"));
        // Additional fields...
    }}
    // Additional hotel documents
);

// Upload documents to the index
IndexDocumentsResult result = searchClient.uploadDocuments(DOCUMENTS);
for (IndexingResult r : result.getResults()) {
    System.out.println("Key: %s, Succeeded: %s".formatted(r.getKey(), r.isSucceeded()));
}

يتفاعل كودك مع فهرس بحث محدد مستضاف في خدمة Azure AI Search الخاصة بك من خلال SearchClient، وهو الكائن الرئيسي الذي توفره حزمة azure-search-documents. يوفر الوصول SearchClient إلى عمليات مثل:

  • استيعاب البيانات: uploadDocuments, mergeDocuments, deleteDocuments

  • عمليات البحث: search, autocomplete, suggest

استعلام الفهرس

تظهر الاستعلامات في ملفات البحث أنماط بحث مختلفة. تستند استعلامات المتجهات النموذجية إلى سلسلتين:

  • سلسلة بحث كاملة النص: "historic hotel walk to restaurants and shopping"

  • سلسلة استعلام المتجه: "quintessential lodging near running trails, eateries, retail" (موجهة إلى تمثيل رياضي)

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

تبدأ الأمثلة التالية باستعلام متجه أساسي وتضيف تدريجيا فلاتر، وبحث في الكلمات المفتاحية، وإعادة ترتيب دلالي.

SearchSingle.java يوضح سيناريو أساسي حيث تريد العثور على أوصاف مستندات تتطابق بشكل وثيق مع سلسلة استعلام المتجه. VectorizedQuery تكوين البحث المتجه:

  • setKNearestNeighborsCount() يحد من عدد النتائج التي يتم إرجاعها بناء على تشابه المتجهات.
  • setFields() يحدد الحقل المتجه الذي يجب البحث ضده.
var vectorQuery = new VectorizedQuery(QueryVector.getVectorList())
    .setKNearestNeighborsCount(5)
    .setFields("DescriptionVector")
    .setExhaustive(true);

var vectorSearchOptions = new VectorSearchOptions()
    .setQueries(vectorQuery)
    .setFilterMode(VectorFilterMode.POST_FILTER);

var searchOptions = new SearchOptions()
    .setTop(7)
    .setIncludeTotalCount(true)
    .setSelect("HotelId", "HotelName", "Description", "Category", "Tags")
    .setVectorSearchOptions(vectorSearchOptions);

var results = searchClient.search("*", searchOptions, Context.NONE);

for (SearchResult result : results) {
    SearchDocument document = result.getDocument(SearchDocument.class);
    System.out.println("HotelId: %s, HotelName: %s, Score: %s".formatted(
        document.get("HotelId"), document.get("HotelName"), result.getScore()));
}

البحث باتجاه واحد باستخدام مرشح

في Azure AI Search، ينطبق filters على الحقول غير المتجهية في الفهرس. SearchSingleWithFilter.java فلاتر في Tags الملعب لتصفية أي فنادق لا توفر واي فاي مجاني.

var vectorQuery = new VectorizedQuery(QueryVector.getVectorList())
    .setKNearestNeighborsCount(5)
    .setFields("DescriptionVector")
    .setExhaustive(true);

var vectorSearchOptions = new VectorSearchOptions()
    .setQueries(vectorQuery)
    .setFilterMode(VectorFilterMode.POST_FILTER);

// Add filter for "free wifi" tag
var searchOptions = new SearchOptions()
    .setTop(7)
    .setIncludeTotalCount(true)
    .setSelect("HotelId", "HotelName", "Description", "Category", "Tags")
    .setFilter("Tags/any(tag: tag eq 'free wifi')")
    .setVectorSearchOptions(vectorSearchOptions);

var results = searchClient.search("*", searchOptions, Context.NONE);

البحث باتجاه واحد باستخدام مرشح جغرافي

يمكنك تحديد مرشح جغرافي مكاني لتقييد النتائج بمنطقة جغرافية محددة. SearchSingleWithGeoFilter.java يحدد نقطة جغرافية (واشنطن العاصمة، باستخدام إحداثيات خطوط الطول وخط العرض) ويعيد الفنادق ضمن 300 كيلومتر. setFilterMode الطريقة التي يتم استدعاؤها VectorSearchOptions، تحدد متى يعمل المرشح. في هذه الحالة، POST_FILTER يتم تشغيل المرشح بعد البحث المتجه.

var searchOptions = new SearchOptions()
    .setTop(5)
    .setIncludeTotalCount(true)
    .setSelect("HotelId", "HotelName", "Category", "Description",
               "Address/City", "Address/StateProvince")
    .setFacets("Address/StateProvince")
    .setFilter("geo.distance(Location, geography'POINT(-77.03241 38.90166)') le 300")
    .setVectorSearchOptions(vectorSearchOptions);

يجمع البحث الهجين بين استعلامات النص الكامل والاستعلامات المتجهية في طلب واحد. SearchHybrid.java يشغل كلا نوعي الاستعلام في نفس الوقت، ثم يستخدم دمج الترتيب المتبادل (RRF) لدمج النتائج في تصنيف موحد. يستخدم RRF عكس ترتيب النتائج من كل مجموعة نتائج لإنتاج تصنيف مدمج. لاحظ أن درجات البحث الهجين أصغر بشكل موحد من درجات الاستعلام الفردي.

var vectorQuery = new VectorizedQuery(QueryVector.getVectorList())
    .setKNearestNeighborsCount(5)
    .setFields("DescriptionVector")
    .setExhaustive(true);

var vectorSearchOptions = new VectorSearchOptions()
    .setQueries(vectorQuery)
    .setFilterMode(VectorFilterMode.POST_FILTER);

var searchOptions = new SearchOptions()
    .setTop(5)
    .setIncludeTotalCount(true)
    .setSelect("HotelId", "HotelName", "Description", "Category", "Tags")
    .setVectorSearchOptions(vectorSearchOptions);

// Pass both text query and vector search options
var results = searchClient.search(
    "historic hotel walk to restaurants and shopping",
    searchOptions, Context.NONE);

SearchSemanticHybrid.java يظهر التصنيف الدلالي، الذي يعيد ترتيب النتائج بناء على فهم اللغة.

var vectorQuery = new VectorizedQuery(QueryVector.getVectorList())
    .setKNearestNeighborsCount(5)
    .setFields("DescriptionVector")
    .setExhaustive(true);

var vectorSearchOptions = new VectorSearchOptions()
    .setQueries(vectorQuery)
    .setFilterMode(VectorFilterMode.POST_FILTER);

SemanticSearchOptions semanticSearchOptions = new SemanticSearchOptions()
    .setSemanticConfigurationName("semantic-config");

var searchOptions = new SearchOptions()
    .setTop(5)
    .setIncludeTotalCount(true)
    .setSelect("HotelId", "HotelName", "Category", "Description")
    .setQueryType(QueryType.SEMANTIC)
    .setSemanticSearchOptions(semanticSearchOptions)
    .setVectorSearchOptions(vectorSearchOptions);

var results = searchClient.search(
    "historic hotel walk to restaurants and shopping",
    searchOptions, Context.NONE);

قارن هذه النتائج مع نتائج البحث الهجينة من الاستعلام السابق. بدون إعادة ترتيب دلالية، يحتل فندق سوبلايم بالاس المرتبة الأولى لأن دمج الترتيب المتبادل (RRF) يجمع بين درجات النص والمتجه لإنتاج نتيجة مدمجة. بعد إعادة ترتيب دلالية، ينتقل فندق Swirling Currents إلى الصدارة.

يستخدم المصنف الدلالي نماذج فهم الآلة لتقييم مدى توافق كل نتيجة مع نية الاستعلام. وصف فندق التيارات الدوامة يذكر "walking access to shopping, dining, entertainment and the city center"، وهذا يتوافق بشكل وثيق مع استعلام "walk to restaurants and shopping"البحث . هذا التوافق الدلالي في تناول الطعام والتسوق القريب يرفعه فوق فندق سوبلايم بالاس، الذي لا يركز على المرافق القابلة للمشي في وصفه.

المسارات الرئيسية:

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

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

تنظيف الموارد

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

في بوابة Azure، اختر All resources أو Resource groups من اللوحة اليسرى للعثور على الموارد وإدارتها. يمكنك حذف الموارد بشكل فردي أو حذف مجموعة الموارد لإزالة كل الموارد دفعة واحدة.

وإلا، شغل الأمر التالي لحذف الفهرس الذي أنشأته في هذا البدء السريع.

mvn compile exec:java "-Dexec.mainClass=com.example.search.DeleteIndex"

في هذا البدء السريع، تستخدم مكتبة العملاء Azure AI Search ل JavaScript لإنشاء وتحميل واستعلام <فهرس متجه 1> . توفر مكتبة عملاء جافا سكريبت تجريدا على واجهات برمجة تطبيقات REST لعمليات الفهرسة.

في Azure AI Search، يحتوي مؤشر المتجهات على مخطط فهرس يحدد الحقول المتجهية وغير المتجهية، وتكوين بحث متجهات للخوارزميات التي تنشئ مساحة التضمين، وإعدادات على تعريفات الحقول المتجهية التي يتم تقييمها عند وقت الاستعلام. الفهارس - إنشاء أو تحديث (REST API) ينشئ فهرس المتجه.

تلميح

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

تكوين الوصول

قبل أن تبدأ، تأكد من أن لديك صلاحيات للوصول إلى المحتوى والعمليات في Azure AI Search. يستخدم هذا البدء السريع معرف Microsoft Entra ID للمصادقة والوصول القائم على الأدوار للتفويض. يجب أن تكون Owner أو User Access Administrator لتعيين الأدوار. إذا لم تكن الأدوار ممكنة، فاستخدم المصادقة المستندة إلى المفتاح بدلا من ذلك.

لتكوين الوصول الموصى به المستند إلى الدور:

  1. فعل access المعتمدة على الأدوار search service.

  2. قم بتعيين الأدوار التالية لحساب المستخدم الخاص بك.

    • Search Service المساهم

    • مساهم بيانات فهرس البحث

    • قارئ بيانات فهرس البحث

الحصول على نقطة النهاية

كل خدمة Azure AI Search لديها endpoint، وهو رابط فريد يحدد ويوفر الوصول إلى الشبكة للخدمة. في قسم لاحق، تحدد هذه النقطة النهائية للاتصال بخدمة البحث الخاصة بك بشكل برمجي.

للحصول على نقطة النهاية:

  1. انتقل إلى خدمة البحث في مدخل Microsoft Azure.

  2. من الجزء الأيمن، حدد نظرة عامة.

  3. دون نقطة النهاية، والتي يجب أن تبدو https://my-service.search.windows.net.

إعداد البيئة

  1. استخدم Git لاستنساخ مستودع العينات.

    git clone https://github.com/Azure-Samples/azure-search-javascript-samples

  2. انتقل إلى مجلد البدء السريع.

    cd azure-search-javascript-samples/quickstart-vector-js

  3. في sample.env، استبدل قيمة البديل المؤقت ل AZURE_SEARCH_ENDPOINT بعنوان URL الذي حصلت عليه في Get endpoint.

  4. أعد تسمية sample.env إلى .env.

    mv sample.env .env

  5. ثبّت التبعيات.

    npm install

    عند اكتمال التثبيت، يجب أن ترى مجلد node_modules في مجلد project.

  6. للمصادقة بدون مفتاح باستخدام Microsoft Entra ID، سجل الدخول إلى حسابك في Azure. إذا كان لديك عدة اشتراكات، اختر الاشتراك الذي يحتوي على خدمة Azure AI Search الخاصة بك.

    az login

تشغيل التعليمات البرمجية

  1. أنشئ فهرس متجه.

    node -r dotenv/config src/createIndex.js

  2. قم بتحميل المستندات التي تحتوي على تضمينات محسوبة مسبقا.

    node -r dotenv/config src/uploadDocuments.js

  3. شغل استعلام بحث متجه.

    node -r dotenv/config src/searchSingle.js

  4. (اختياري) قم بتشغيل تنويعات إضافية للاستعلام.

    node -r dotenv/config src/searchSingleWithFilter.js
node -r dotenv/config src/searchSingleWithFilterGeo.js
node -r dotenv/config src/searchHybrid.js
node -r dotenv/config src/searchSemanticHybrid.js

الاخراج

يظهر مخرجات createIndex.js اسم الفهرس والتأكيد.

Using Azure Search endpoint: https://<search-service-name>.search.windows.net
Using Azure Search index: hotels-vector-quickstart
Creating index...
hotels-vector-quickstart created

يظهر الناتج حالة uploadDocuments.js النجاح لكل مستند مفهرس.

Uploading documents...
Key: 1, Succeeded: true, ErrorMessage: none
Key: 2, Succeeded: true, ErrorMessage: none
Key: 3, Succeeded: true, ErrorMessage: none
Key: 4, Succeeded: true, ErrorMessage: none
Key: 48, Succeeded: true, ErrorMessage: none
Key: 49, Succeeded: true, ErrorMessage: none
Key: 13, Succeeded: true, ErrorMessage: none
Waiting for indexing... Current count: 0
All documents indexed successfully.

يظهر الناتج searchSingle.js نتائج البحث المتجهية المرتبة حسب درجة التشابه.

Single Vector search found 5
- HotelId: 48, HotelName: Nordick's Valley Motel, Tags: ["continental breakfast","air conditioning","free wifi"], Score 0.6605852
- HotelId: 13, HotelName: Luxury Lion Resort, Tags: ["bar","concierge","restaurant"], Score 0.6333684
- HotelId: 4, HotelName: Sublime Palace Hotel, Tags: ["concierge","view","air conditioning"], Score 0.605672
- HotelId: 49, HotelName: Swirling Currents Hotel, Tags: ["air conditioning","laundry service","24-hour front desk service"], Score 0.6026341
- HotelId: 2, HotelName: Old Century Hotel, Tags: ["pool","free wifi","air conditioning","concierge"], Score 0.57902366

فهم الكود

ملاحظة

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

الآن بعد أن قمت بتشغيل التعليمات البرمجية ، دعنا نقسم الخطوات الرئيسية:

  1. إنشاء فهرس متجه
  2. تحميل المستندات إلى الفهرس
  3. استعلام الفهرس

إنشاء فهرس متجه

قبل أن تضيف المحتوى إلى Azure AI Search، يجب عليك إنشاء فهرس لتحديد كيفية تخزين وهيكلة المحتوى.

مخطط الفهرس منظم حول محتوى الفنادق. تتكون بيانات العينة من أوصاف متجهة وغير عاملة للفنادق الوهمية. الكود التالي في createIndex.js ينشئ مخطط الفهرس، بما في ذلك حقل DescriptionVectorالمتجهات .

const searchFields = [
    { name: "HotelId", type: "Edm.String", key: true, sortable: true, filterable: true, facetable: true },
    { name: "HotelName", type: "Edm.String", searchable: true, filterable: true },
    { name: "Description", type: "Edm.String", searchable: true },
    {
        name: "DescriptionVector",
        type: "Collection(Edm.Single)",
        searchable: true,
        vectorSearchDimensions: 1536,
        vectorSearchProfileName: "vector-profile"
    },
    { name: "Category", type: "Edm.String", filterable: true, facetable: true },
    { name: "Tags", type: "Collection(Edm.String)", filterable: true },
    // Additional fields: ParkingIncluded, LastRenovationDate, Rating, Address, Location
];

const vectorSearch = {
    profiles: [
        {
            name: "vector-profile",
            algorithmConfigurationName: "vector-search-algorithm"
        }
    ],
    algorithms: [
        {
            name: "vector-search-algorithm",
            kind: "hnsw",
            parameters: { m: 4, efConstruction: 400, efSearch: 1000, metric: "cosine" }
        }
    ]
};

const semanticSearch = {
    configurations: [
        {
            name: "semantic-config",
            prioritizedFields: {
                contentFields: [{ name: "Description" }],
                keywordsFields: [{ name: "Category" }],
                titleField: { name: "HotelName" }
            }
        }
    ]
};

const searchIndex = {
    name: indexName,
    fields: searchFields,
    vectorSearch: vectorSearch,
    semanticSearch: semanticSearch,
    suggesters: [{ name: "sg", searchMode: "analyzingInfixMatching", sourceFields: ["HotelName"] }]
};

const result = await indexClient.createOrUpdateIndex(searchIndex);

المسارات الرئيسية:

  • يمكنك تعريف فهرس عن طريق إنشاء قائمة حقول.

  • يدعم هذا الفهرس تحديدا قدرات بحث متعددة:

  • يجب أن تتطابق الخاصية vectorSearchDimensions مع حجم مخرج نموذج التضمين الخاص بك. يستخدم هذا البدء السريع 1,536 بعدا ليتناسب مع النموذج text-embedding-ada-002 .

  • يحدد هذا vectorSearch التكوين خوارزمية أقرب جار تقريبي (ANN). تشمل الخوارزميات المدعومة العالم الصغير القابل للملاحة الهرمي (HNSW) والجار الشامل K-أقرب جار (KNN). لمزيد من المعلومات، راجع الصلة في البحث المتجه.

تحميل المستندات إلى الفهرس

الفهارس التي تم إنشاؤها حديثا فارغة. لتعبئة فهرس وجعله قابلا للبحث، يجب تحميل مستندات JSON التي تتوافق مع مخطط الفهرس.

في Azure AI Search، تعمل المستندات كمدخلات للفهرسة ومخرجات للاستعلامات. للتبسيط، يوفر هذا البدء السريع نماذج من مستندات الفنادق مع متجهات محسوبة مسبقا. في سيناريوهات الإنتاج، غالبا ما يتم سحب المحتوى من مصادر بيانات متصلة وتحويله إلى JSON باستخدام الفهارس.

الرمز التالي في uploadDocuments.js يرفع المستندات إلى خدمة البحث الخاصة بك.

const DOCUMENTS = [
    // Array of hotel documents with embedded 1536-dimension vectors
    // Each document contains: HotelId, HotelName, Description, DescriptionVector,
    // Category, Tags, ParkingIncluded, LastRenovationDate, Rating, Address, Location
];

const searchClient = new SearchClient(searchEndpoint, indexName, credential);

const result = await searchClient.uploadDocuments(DOCUMENTS);
for (const r of result.results) {
    console.log(`Key: ${r.key}, Succeeded: ${r.succeeded}`);
}

يتفاعل كودك مع فهرس بحث محدد مستضاف في خدمة Azure AI Search الخاصة بك من خلال SearchClient، وهو الكائن الرئيسي الذي توفره حزمة @azure/search-documents. يوفر الوصول SearchClient إلى عمليات الفهرس، مثل:

  • استيعاب البيانات: uploadDocuments, mergeDocuments, deleteDocuments

  • عمليات البحث: search, autocomplete, suggest

استعلام الفهرس

تظهر الاستعلامات في ملفات البحث أنماط بحث مختلفة. تستند استعلامات المتجهات النموذجية إلى سلسلتين:

  • سلسلة بحث كاملة النص: "historic hotel walk to restaurants and shopping"

  • سلسلة استعلام المتجه: "quintessential lodging near running trails, eateries, retail" (موجهة إلى تمثيل رياضي)

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

تبدأ الأمثلة التالية باستعلام متجه أساسي وتضيف تدريجيا فلاتر، وبحث في الكلمات المفتاحية، وإعادة ترتيب دلالي.

searchSingle.js يوضح سيناريو أساسي حيث تريد العثور على أوصاف مستندات تتطابق بشكل وثيق مع سلسلة استعلام المتجه. يقوم الكائن vectorQuery بتكوين البحث المتجه:

  • kNearestNeighborsCount يحد من عدد النتائج التي يتم إرجاعها بناء على تشابه المتجهات.
  • fields يحدد الحقل المتجه الذي يجب البحث ضده.
const vectorQuery = {
    vector: vector,
    kNearestNeighborsCount: 5,
    fields: ["DescriptionVector"],
    kind: "vector",
    exhaustive: true
};

const searchOptions = {
    top: 7,
    select: ["HotelId", "HotelName", "Description", "Category", "Tags"],
    includeTotalCount: true,
    vectorSearchOptions: {
        queries: [vectorQuery],
        filterMode: "postFilter"
    }
};

const results = await searchClient.search("*", searchOptions);

for await (const result of results.results) {
    const doc = result.document;
    console.log(`HotelId: ${doc.HotelId}, HotelName: ${doc.HotelName}, Score: ${result.score}`);
}

البحث باتجاه واحد باستخدام مرشح

في Azure AI Search، ينطبق filters على الحقول غير المتجهية في الفهرس. searchSingleWithFilter.js فلاتر في Tags الملعب لتصفية أي فنادق لا توفر واي فاي مجاني.

const searchOptions = {
    top: 7,
    select: ["HotelId", "HotelName", "Description", "Category", "Tags"],
    includeTotalCount: true,
    filter: "Tags/any(tag: tag eq 'free wifi')", // Adding filter for "free wifi" tag
    vectorSearchOptions: {
        queries: [vectorQuery],
        filterMode: "postFilter"
    }
};

const results = await searchClient.search("*", searchOptions);

البحث باتجاه واحد باستخدام مرشح جغرافي

يمكنك تحديد مرشح جغرافي مكاني لتقييد النتائج بمنطقة جغرافية محددة. searchSingleWithGeoFilter.js يحدد نقطة جغرافية (واشنطن العاصمة، باستخدام إحداثيات خطوط الطول وخط العرض) ويعيد الفنادق ضمن 300 كيلومتر. تحدد هذه الخاصية filterMode متى يعمل المرشح. في هذه الحالة، postFilter يتم تشغيل المرشح بعد البحث المتجه.

const searchOptions = {
    top: 5,
    includeTotalCount: true,
    select: ["HotelId", "HotelName", "Category", "Description", "Address/City", "Address/StateProvince"],
    facets: ["Address/StateProvince"],
    filter: "geo.distance(Location, geography'POINT(-77.03241 38.90166)') le 300",
    vectorSearchOptions: {
        queries: [vectorQuery],
        filterMode: "postFilter"
    }
};

يجمع البحث الهجين بين استعلامات النص الكامل والاستعلامات المتجهية في طلب واحد. searchHybrid.js يشغل كلا نوعي الاستعلام في نفس الوقت، ثم يستخدم دمج الترتيب المتبادل (RRF) لدمج النتائج في تصنيف موحد. يستخدم RRF عكس ترتيب النتائج من كل مجموعة نتائج لإنتاج تصنيف مدمج. لاحظ أن درجات البحث الهجين أصغر بشكل موحد من درجات الاستعلام الفردي.

const vectorQuery = {
    vector: vector,
    kNearestNeighborsCount: 5,
    fields: ["DescriptionVector"],
    kind: "vector",
    exhaustive: true
};

const searchOptions = {
    top: 5,
    includeTotalCount: true,
    select: ["HotelId", "HotelName", "Description", "Category", "Tags"],
    vectorSearchOptions: {
        queries: [vectorQuery],
        filterMode: "postFilter"
    }
};

// Use search text for keyword search (hybrid search = vector + keyword)
const searchText = "historic hotel walk to restaurants and shopping";
const results = await searchClient.search(searchText, searchOptions);

searchSemanticHybrid.js يظهر التصنيف الدلالي، الذي يعيد ترتيب النتائج بناء على فهم اللغة.

const searchOptions = {
    top: 5,
    includeTotalCount: true,
    select: ["HotelId", "HotelName", "Category", "Description"],
    queryType: "semantic",
    semanticSearchOptions: {
        configurationName: "semantic-config"
    },
    vectorSearchOptions: {
        queries: [vectorQuery],
        filterMode: "postFilter"
    }
};

const searchText = "historic hotel walk to restaurants and shopping";
const results = await searchClient.search(searchText, searchOptions);

for await (const result of results.results) {
    console.log(`Score: ${result.score}, Re-ranker Score: ${result.rerankerScore}`);
}

قارن هذه النتائج مع نتائج البحث الهجينة من الاستعلام السابق. بدون إعادة ترتيب دلالية، يحتل فندق سوبلايم بالاس المرتبة الأولى لأن دمج الترتيب المتبادل (RRF) يجمع بين درجات النص والمتجه لإنتاج نتيجة مدمجة. بعد إعادة ترتيب دلالية، ينتقل فندق Swirling Currents إلى الصدارة.

يستخدم المصنف الدلالي نماذج فهم الآلة لتقييم مدى توافق كل نتيجة مع نية الاستعلام. وصف فندق التيارات الدوامة يذكر "walking access to shopping, dining, entertainment and the city center"، وهذا يتوافق بشكل وثيق مع استعلام "walk to restaurants and shopping"البحث . هذا التوافق الدلالي في تناول الطعام والتسوق القريب يرفعه فوق فندق سوبلايم بالاس، الذي لا يركز على المرافق القابلة للمشي في وصفه.

المسارات الرئيسية:

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

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

تنظيف الموارد

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

في بوابة Azure، اختر All resources أو Resource groups من اللوحة اليسرى للعثور على الموارد وإدارتها. يمكنك حذف الموارد بشكل فردي أو حذف مجموعة الموارد لإزالة كل الموارد دفعة واحدة.

وإلا، شغل الأمر التالي لحذف الفهرس الذي أنشأته في هذا البدء السريع.

node -r dotenv/config src/deleteIndex.js

في هذه البداية السريعة، تستخدم مكتبة العملاء Azure AI Search ل Python لإنشاء وتحميل واستعلام <فهرس متجه c1>vector. توفر مكتبة عملاء Python تجريدا عبر واجهات برمجة تطبيقات REST لعمليات الفهرس.

في Azure AI Search، يحتوي مؤشر المتجهات على مخطط فهرس يحدد الحقول المتجهية وغير المتجهية، وتكوين بحث متجهات للخوارزميات التي تنشئ مساحة التضمين، وإعدادات على تعريفات الحقول المتجهية التي يتم تقييمها عند وقت الاستعلام. الفهارس - إنشاء أو تحديث (REST API) ينشئ فهرس المتجه.

تلميح

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

تكوين الوصول

قبل أن تبدأ، تأكد من أن لديك صلاحيات للوصول إلى المحتوى والعمليات في Azure AI Search. يستخدم هذا البدء السريع معرف Microsoft Entra ID للمصادقة والوصول القائم على الأدوار للتفويض. يجب أن تكون Owner أو User Access Administrator لتعيين الأدوار. إذا لم تكن الأدوار ممكنة، فاستخدم المصادقة المستندة إلى المفتاح بدلا من ذلك.

لتكوين الوصول الموصى به المستند إلى الدور:

  1. فعل access المعتمدة على الأدوار search service.

  2. قم بتعيين الأدوار التالية لحساب المستخدم الخاص بك.

    • Search Service المساهم

    • مساهم بيانات فهرس البحث

    • قارئ بيانات فهرس البحث

الحصول على نقطة النهاية

كل خدمة Azure AI Search لديها endpoint، وهو رابط فريد يحدد ويوفر الوصول إلى الشبكة للخدمة. في قسم لاحق، تحدد هذه النقطة النهائية للاتصال بخدمة البحث الخاصة بك بشكل برمجي.

للحصول على نقطة النهاية:

  1. انتقل إلى خدمة البحث في مدخل Microsoft Azure.

  2. من الجزء الأيمن، حدد نظرة عامة.

  3. دون نقطة النهاية، والتي يجب أن تبدو https://my-service.search.windows.net.

إعداد البيئة

  1. استخدم Git لاستنساخ مستودع العينات.

    git clone https://github.com/Azure-Samples/azure-search-python-samples

  2. انتقل إلى مجلد البدء السريع وافتحه في Visual Studio Code.

    cd azure-search-python-samples/Quickstart-Vector-Search
code .

  3. في sample.env، استبدل قيمة البديل المؤقت ل AZURE_SEARCH_ENDPOINT بعنوان URL الذي حصلت عليه في Get endpoint.

  4. أعد تسمية sample.env إلى .env.

    mv sample.env .env

  5. افتح vector-search-quickstart.ipynb.

  6. اضغط Ctrl+Shift+P، اختر نوت بوتبوت: اختر نواة نوت بوتبوت، واتبع التعليمات لإنشاء بيئة افتراضية. اختر requirements.txt للتبعيات.

    عند الانتهاء، يجب أن ترى مجلد .venv في مجلد project.

  7. للمصادقة بدون مفتاح باستخدام Microsoft Entra ID، سجل الدخول إلى حسابك في Azure. إذا كان لديك عدة اشتراكات، اختر الاشتراك الذي يحتوي على خدمة Azure AI Search الخاصة بك.

    az login

تشغيل التعليمات البرمجية

  1. شغل الخلية Install packages and set variables لتثبيت الحزم المطلوبة ومتغيرات بيئة التحميل.

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

الاخراج

كل خلية كود تطبع مخرجاتها إلى الدفتر الملاحظ. المثال التالي هو مخرجات ، Single vector searchالتي تعرض نتائج البحث المتجهية المرتبة حسب درجة التشابه.

Total results: 7
- HotelId: 48, HotelName: Nordick's Valley Motel, Category: Boutique
- HotelId: 13, HotelName: Luxury Lion Resort, Category: Luxury
- HotelId: 4, HotelName: Sublime Palace Hotel, Category: Boutique
- HotelId: 49, HotelName: Swirling Currents Hotel, Category: Suite
- HotelId: 2, HotelName: Old Century Hotel, Category: Boutique

فهم الكود

ملاحظة

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

الآن بعد أن قمت بتشغيل التعليمات البرمجية ، دعنا نقسم الخطوات الرئيسية:

  1. إنشاء فهرس متجه
  2. تحميل المستندات إلى الفهرس
  3. استعلام الفهرس

إنشاء فهرس متجه

قبل أن تضيف المحتوى إلى Azure AI Search، يجب عليك إنشاء فهرس لتحديد كيفية تخزين وهيكلة المحتوى.

مخطط الفهرس منظم حول محتوى الفنادق. تتكون بيانات العينة من أوصاف متجهة وغير عاملة للفنادق الوهمية. Create an index الخلية في الدفتر تنشئ مخطط الفهرس، بما في ذلك حقل DescriptionVectorالمتجهات .

fields = [
    SimpleField(name="HotelId", type=SearchFieldDataType.String, key=True, filterable=True),
    SearchableField(name="HotelName", type=SearchFieldDataType.String, sortable=True),
    SearchableField(name="Description", type=SearchFieldDataType.String),
    SearchField(
        name="DescriptionVector",
        type=SearchFieldDataType.Collection(SearchFieldDataType.Single),
        searchable=True,
        vector_search_dimensions=1536,
        vector_search_profile_name="my-vector-profile"
    ),
    SearchableField(name="Category", type=SearchFieldDataType.String, sortable=True, filterable=True, facetable=True),
    SearchField(name="Tags", type=SearchFieldDataType.Collection(SearchFieldDataType.String), searchable=True, filterable=True, facetable=True),
    # Additional fields omitted for brevity
]

المسارات الرئيسية:

  • يمكنك تعريف فهرس عن طريق إنشاء قائمة حقول. يتم إنشاء كل حقل باستخدام أسلوب مساعد يحدد نوع الحقل وإعداداته.

  • يدعم هذا الفهرس تحديدا قدرات بحث متعددة:

  • يجب أن تتطابق الخاصية vector_search_dimensions مع حجم مخرج نموذج التضمين الخاص بك. يستخدم هذا البدء السريع 1,536 بعدا ليتناسب مع النموذج text-embedding-ada-002 .

  • يحدد هذا VectorSearch التكوين خوارزمية أقرب جار تقريبي (ANN). تشمل الخوارزميات المدعومة العالم الصغير القابل للملاحة الهرمي (HNSW) والجار الشامل K-أقرب جار (KNN). لمزيد من المعلومات، راجع الصلة في البحث المتجه.

تحميل المستندات إلى الفهرس

الفهارس التي تم إنشاؤها حديثا فارغة. لتعبئة فهرس وجعله قابلا للبحث، يجب تحميل مستندات JSON التي تتوافق مع مخطط الفهرس.

في Azure AI Search، تعمل المستندات كمدخلات للفهرسة ومخرجات للاستعلامات. للتبسيط، يوفر هذا البدء السريع نماذج من مستندات الفنادق مع متجهات محسوبة مسبقا. في سيناريوهات الإنتاج، غالبا ما يتم سحب المحتوى من مصادر بيانات متصلة وتحويله إلى JSON باستخدام الفهارس.

تقوم الخلايا Create documents payload وتحميل Upload the documents المستندات إلى الفهرس.

documents = [
    # List of hotel documents with embedded 1536-dimension vectors
    # Each document contains: HotelId, HotelName, Description, DescriptionVector,
    # Category, Tags, ParkingIncluded, LastRenovationDate, Rating, Address, Location
]

search_client = SearchClient(
    endpoint=search_endpoint,
    index_name=index_name,
    credential=credential
)

result = search_client.upload_documents(documents=documents)
for r in result:
    print(f"Key: {r.key}, Succeeded: {r.succeeded}, ErrorMessage: {r.error_message}")

يتفاعل كودك مع فهرس بحث محدد مستضاف في خدمة Azure AI Search الخاصة بك من خلال SearchClient، وهو الكائن الرئيسي الذي توفره حزمة azure-search-documents. يوفر الوصول SearchClient إلى عمليات الفهرس، مثل:

  • استيعاب البيانات: upload_documents(), merge_documents(), delete_documents()

  • عمليات البحث: search(), autocomplete(), suggest()

استعلام الفهرس

تظهر الاستعلامات في الدفتر أنماط بحث مختلفة. تستند استعلامات المتجهات النموذجية إلى سلسلتين:

  • سلسلة بحث كاملة النص: "historic hotel walk to restaurants and shopping"

  • سلسلة استعلام المتجه: "quintessential lodging near running trails, eateries, retail" (موجهة إلى تمثيل رياضي)

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

تبدأ الأمثلة التالية باستعلام متجه أساسي وتضيف تدريجيا فلاتر، وبحث في الكلمات المفتاحية، وإعادة ترتيب دلالي.

توضح الخلية Single vector search سيناريو أساسي حيث تريد العثور على أوصاف المستندات التي تطابق بشكل وثيق سلسلة استعلام المتجه. VectorizedQuery تكوين البحث المتجه:

  • k_nearest_neighbors يحد من عدد النتائج التي يتم إرجاعها بناء على تشابه المتجهات.
  • fields يحدد الحقل المتجه الذي يجب البحث ضده.
vector_query = VectorizedQuery(
    vector=vector,
    k_nearest_neighbors=5,
    fields="DescriptionVector",
    kind="vector",
    exhaustive=True
)

results = search_client.search(
    vector_queries=[vector_query],
    select=["HotelId", "HotelName", "Description", "Category", "Tags"],
    top=5,
    include_total_count=True
)

البحث باتجاه واحد باستخدام مرشح

في Azure AI Search، ينطبق filters على الحقول غير المتجهية في الفهرس. Single vector search with filter تصفية الهاتف المحمول في Tags الملعب لتصفية أي فنادق لا توفر واي فاي مجاني.

# vector_query omitted for brevity

results = search_client.search(
    vector_queries=[vector_query],
    filter="Tags/any(tag: tag eq 'free wifi')",
    select=["HotelId", "HotelName", "Description", "Category", "Tags"],
    top=7,
    include_total_count=True
)

البحث باتجاه واحد باستخدام مرشح جغرافي

يمكنك تحديد مرشح جغرافي مكاني لتقييد النتائج بمنطقة جغرافية محددة. تحدد الخلية Single vector search with geo filter نقطة جغرافية (واشنطن العاصمة، باستخدام إحداثيات خطوط الطول والعرض) وتعيد الفنادق ضمن 300 كيلومتر. يحدد المعامل vector_filter_mode متى يعمل الفلتر. في هذه الحالة، postFilter يتم تشغيل المرشح بعد البحث المتجه.

# vector_query omitted for brevity

results = search_client.search(
    include_total_count=True,
    top=5,
    select=[
        "HotelId", "HotelName", "Category", "Description", "Address/City", "Address/StateProvince"
    ],
    facets=["Address/StateProvince"],
    filter="geo.distance(Location, geography'POINT(-77.03241 38.90166)') le 300",
    vector_filter_mode="postFilter",
    vector_queries=[vector_query]
)

يجمع البحث الهجين بين استعلامات النص الكامل والاستعلامات المتجهية في طلب واحد. تقوم الخلية Hybrid search بتشغيل كلا نوعي الاستعلام في نفس الوقت، ثم تستخدم دمج الترتيب المتبادل (RRF) لدمج النتائج في تصنيف موحد. يستخدم RRF عكس ترتيب النتائج من كل مجموعة نتائج لإنتاج تصنيف مدمج. لاحظ أن درجات البحث الهجين أصغر بشكل موحد من درجات الاستعلام الفردي.

# vector_query omitted for brevity

results = search_client.search(
    search_text="historic hotel walk to restaurants and shopping",
    vector_queries=[vector_query],
    select=["HotelId", "HotelName", "Description", "Category", "Tags"],
    top=5,
    include_total_count=True
)

تظهر الخلية Semantic hybrid searchالترتيب الدلالي، الذي يعيد ترتيب النتائج بناء على فهم اللغة.

# vector_query omitted for brevity

results = search_client.search(
    search_text="historic hotel walk to restaurants and shopping",
    vector_queries=[vector_query],
    select=["HotelId", "HotelName", "Category", "Description"],
    query_type="semantic",
    semantic_configuration_name="my-semantic-config",
    top=5,
    include_total_count=True
)

قارن هذه النتائج مع نتائج البحث الهجينة من الاستعلام السابق. بدون إعادة ترتيب دلالية، يحتل فندق سوبلايم بالاس المرتبة الأولى لأن دمج الترتيب المتبادل (RRF) يجمع بين درجات النص والمتجه لإنتاج نتيجة مدمجة. بعد إعادة ترتيب دلالية، ينتقل فندق Swirling Currents إلى الصدارة.

يستخدم المصنف الدلالي نماذج فهم الآلة لتقييم مدى توافق كل نتيجة مع نية الاستعلام. وصف فندق التيارات الدوامة يذكر "walking access to shopping, dining, entertainment and the city center"، وهذا يتوافق بشكل وثيق مع استعلام "walk to restaurants and shopping"البحث . هذا التوافق الدلالي في تناول الطعام والتسوق القريب يرفعه فوق فندق سوبلايم بالاس، الذي لا يركز على المرافق القابلة للمشي في وصفه.

المسارات الرئيسية:

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

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

تنظيف الموارد

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

في بوابة Azure، اختر All resources أو Resource groups من اللوحة اليسرى للعثور على الموارد وإدارتها. يمكنك حذف الموارد بشكل فردي أو حذف مجموعة الموارد لإزالة كل الموارد دفعة واحدة.

وإلا، يمكنك تشغيل Clean up خلية الكود لحذف الفهرس الذي أنشأته في هذه البداية السريعة.

في هذه البداية السريعة، تستخدم مكتبة العملاء Azure AI Search لجافا سكريبت (المتوافقة مع TypeScript) لإنشاء وتحميل واستعلام <فهرس متجه c1> . توفر مكتبة عملاء جافا سكريبت تجريدا على واجهات برمجة تطبيقات REST لعمليات الفهرسة.

في Azure AI Search، يحتوي مؤشر المتجهات على مخطط فهرس يحدد الحقول المتجهية وغير المتجهية، وتكوين بحث متجهات للخوارزميات التي تنشئ مساحة التضمين، وإعدادات على تعريفات الحقول المتجهية التي يتم تقييمها عند وقت الاستعلام. الفهارس - إنشاء أو تحديث (REST API) ينشئ فهرس المتجه.

تلميح

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

تكوين الوصول

قبل أن تبدأ، تأكد من أن لديك صلاحيات للوصول إلى المحتوى والعمليات في Azure AI Search. يستخدم هذا البدء السريع معرف Microsoft Entra ID للمصادقة والوصول القائم على الأدوار للتفويض. يجب أن تكون Owner أو User Access Administrator لتعيين الأدوار. إذا لم تكن الأدوار ممكنة، فاستخدم المصادقة المستندة إلى المفتاح بدلا من ذلك.

لتكوين الوصول الموصى به المستند إلى الدور:

  1. فعل access المعتمدة على الأدوار search service.

  2. قم بتعيين الأدوار التالية لحساب المستخدم الخاص بك.

    • Search Service المساهم

    • مساهم بيانات فهرس البحث

    • قارئ بيانات فهرس البحث

الحصول على نقطة النهاية

كل خدمة Azure AI Search لديها endpoint، وهو رابط فريد يحدد ويوفر الوصول إلى الشبكة للخدمة. في قسم لاحق، تحدد هذه النقطة النهائية للاتصال بخدمة البحث الخاصة بك بشكل برمجي.

للحصول على نقطة النهاية:

  1. انتقل إلى خدمة البحث في مدخل Microsoft Azure.

  2. من الجزء الأيمن، حدد نظرة عامة.

  3. دون نقطة النهاية، والتي يجب أن تبدو https://my-service.search.windows.net.

إعداد البيئة

  1. استخدم Git لاستنساخ مستودع العينات.

    git clone https://github.com/Azure-Samples/azure-search-javascript-samples

  2. انتقل إلى مجلد البدء السريع.

    cd azure-search-javascript-samples/quickstart-vector-ts

  3. في sample.env، استبدل قيمة البديل المؤقت ل AZURE_SEARCH_ENDPOINT بعنوان URL الذي حصلت عليه في Get endpoint.

  4. أعد تسمية sample.env إلى .env.

    mv sample.env .env

  5. ثبّت التبعيات.

    npm install

    عند اكتمال التثبيت، يجب أن ترى مجلد node_modules في مجلد project.

  6. قم بتجميع ملفات TypeScript إلى JavaScript.

    npm run build

  7. للمصادقة بدون مفتاح باستخدام Microsoft Entra ID، سجل الدخول إلى حسابك في Azure. إذا كان لديك عدة اشتراكات، اختر الاشتراك الذي يحتوي على خدمة Azure AI Search الخاصة بك.

    az login

تشغيل التعليمات البرمجية

  1. أنشئ فهرس متجه.

    node -r dotenv/config dist/createIndex.js

  2. قم بتحميل المستندات التي تحتوي على تضمينات محسوبة مسبقا.

    node -r dotenv/config dist/uploadDocuments.js

  3. شغل استعلام بحث متجه.

    node -r dotenv/config dist/searchSingle.js

  4. (اختياري) قم بتشغيل تنويعات إضافية للاستعلام.

    node -r dotenv/config dist/searchSingleWithFilter.js
node -r dotenv/config dist/searchSingleWithFilterGeo.js
node -r dotenv/config dist/searchHybrid.js
node -r dotenv/config dist/searchSemanticHybrid.js

    ملاحظة

    تقوم هذه الأوامر بتشغيل الملفات المترجمة .js من المجلد dist . يجب تحويل كود TypeScript إلى JavaScript قبل Node.js تتمكن من تنفيذه، ولهذا السبب قمت بتشغيل npm run build.

الاخراج

يظهر مخرجات createIndex.ts اسم الفهرس والتأكيد.

Using Azure Search endpoint: https://<search-service-name>.search.windows.net
Using index name: hotels-vector-quickstart
Creating index...
hotels-vector-quickstart created

يظهر الناتج حالة uploadDocuments.ts النجاح لكل مستند مفهرس.

Uploading documents...
Key: 1, Succeeded: true, ErrorMessage: none
Key: 2, Succeeded: true, ErrorMessage: none
Key: 3, Succeeded: true, ErrorMessage: none
Key: 4, Succeeded: true, ErrorMessage: none
Key: 48, Succeeded: true, ErrorMessage: none
Key: 49, Succeeded: true, ErrorMessage: none
Key: 13, Succeeded: true, ErrorMessage: none
All documents indexed successfully.

يظهر الناتج searchSingle.ts نتائج البحث المتجهية المرتبة حسب درجة التشابه.

Single Vector search found 5
- HotelId: 48, HotelName: Nordick's Valley Motel, Tags: ["continental breakfast","air conditioning","free wifi"], Score 0.6605852
- HotelId: 13, HotelName: Luxury Lion Resort, Tags: ["bar","concierge","restaurant"], Score 0.6333684
- HotelId: 4, HotelName: Sublime Palace Hotel, Tags: ["concierge","view","air conditioning"], Score 0.605672
- HotelId: 49, HotelName: Swirling Currents Hotel, Tags: ["air conditioning","laundry service","24-hour front desk service"], Score 0.6026341
- HotelId: 2, HotelName: Old Century Hotel, Tags: ["pool","free wifi","air conditioning","concierge"], Score 0.57902366

فهم الكود

ملاحظة

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

الآن بعد أن قمت بتشغيل التعليمات البرمجية ، دعنا نقسم الخطوات الرئيسية:

  1. إنشاء فهرس متجه
  2. تحميل المستندات إلى الفهرس
  3. استعلام الفهرس

إنشاء فهرس متجه

قبل أن تضيف المحتوى إلى Azure AI Search، يجب عليك إنشاء فهرس لتحديد كيفية تخزين وهيكلة المحتوى.

مخطط الفهرس منظم حول محتوى الفنادق. تتكون بيانات العينة من أوصاف متجهة وغير عاملة للفنادق الوهمية. الكود التالي في createIndex.ts ينشئ مخطط الفهرس، بما في ذلك حقل DescriptionVectorالمتجهات .

const searchFields: SearchField[] = [
    { name: "HotelId", type: "Edm.String", key: true, sortable: true, filterable: true, facetable: true },
    { name: "HotelName", type: "Edm.String", searchable: true, filterable: true },
    { name: "Description", type: "Edm.String", searchable: true },
    {
        name: "DescriptionVector",
        type: "Collection(Edm.Single)",
        searchable: true,
        vectorSearchDimensions: 1536,
        vectorSearchProfileName: "vector-profile"
    },
    { name: "Category", type: "Edm.String", filterable: true, facetable: true },
    { name: "Tags", type: "Collection(Edm.String)", filterable: true },
    // Additional fields: ParkingIncluded, LastRenovationDate, Rating, Address, Location
];

const vectorSearch: VectorSearch = {
    profiles: [
        {
            name: "vector-profile",
            algorithmConfigurationName: "vector-search-algorithm"
        }
    ],
    algorithms: [
        {
            name: "vector-search-algorithm",
            kind: "hnsw",
            parameters: { m: 4, efConstruction: 400, efSearch: 1000, metric: "cosine" }
        }
    ]
};

const semanticSearch: SemanticSearch = {
    configurations: [
        {
            name: "semantic-config",
            prioritizedFields: {
                contentFields: [{ name: "Description" }],
                keywordsFields: [{ name: "Category" }],
                titleField: { name: "HotelName" }
            }
        }
    ]
};

const searchIndex: SearchIndex = {
    name: indexName,
    fields: searchFields,
    vectorSearch: vectorSearch,
    semanticSearch: semanticSearch,
    suggesters: [{ name: "sg", searchMode: "analyzingInfixMatching", sourceFields: ["HotelName"] }]
};

const result = await indexClient.createOrUpdateIndex(searchIndex);

المسارات الرئيسية:

  • يمكنك تعريف فهرس عن طريق إنشاء قائمة حقول.

  • يدعم هذا الفهرس تحديدا قدرات بحث متعددة:

  • يجب أن تتطابق الخاصية vectorSearchDimensions مع حجم مخرج نموذج التضمين الخاص بك. يستخدم هذا البدء السريع 1,536 بعدا ليتناسب مع النموذج text-embedding-ada-002 .

  • يحدد هذا vectorSearch التكوين خوارزمية أقرب جار تقريبي (ANN). تشمل الخوارزميات المدعومة العالم الصغير القابل للملاحة الهرمي (HNSW) والجار الشامل K-أقرب جار (KNN). لمزيد من المعلومات، راجع الصلة في البحث المتجه.

تحميل المستندات إلى الفهرس

الفهارس التي تم إنشاؤها حديثا فارغة. لتعبئة فهرس وجعله قابلا للبحث، يجب تحميل مستندات JSON التي تتوافق مع مخطط الفهرس.

في Azure AI Search، تعمل المستندات كمدخلات للفهرسة ومخرجات للاستعلامات. للتبسيط، يوفر هذا البدء السريع نماذج من مستندات الفنادق مع متجهات محسوبة مسبقا. في سيناريوهات الإنتاج، غالبا ما يتم سحب المحتوى من مصادر بيانات متصلة وتحويله إلى JSON باستخدام الفهارس.

الرمز التالي في uploadDocuments.ts يرفع المستندات إلى خدمة البحث الخاصة بك.

const DOCUMENTS = [
    // Array of hotel documents with embedded 1536-dimension vectors
    // Each document contains: HotelId, HotelName, Description, DescriptionVector,
    // Category, Tags, ParkingIncluded, LastRenovationDate, Rating, Address, Location
];

const searchClient = new SearchClient(searchEndpoint, indexName, credential);

const result = await searchClient.uploadDocuments(DOCUMENTS);
for (const r of result.results) {
    console.log(`Key: ${r.key}, Succeeded: ${r.succeeded}`);
}

يتفاعل كودك مع فهرس بحث محدد مستضاف في خدمة Azure AI Search الخاصة بك من خلال SearchClient، وهو الكائن الرئيسي الذي توفره حزمة @azure/search-documents. يوفر الوصول SearchClient إلى عمليات الفهرس، مثل:

  • استيعاب البيانات: uploadDocuments, mergeDocuments, deleteDocuments

  • عمليات البحث: search, autocomplete, suggest

استعلام الفهرس

تظهر الاستعلامات في ملفات البحث أنماط بحث مختلفة. تستند استعلامات المتجهات النموذجية إلى سلسلتين:

  • سلسلة بحث كاملة النص: "historic hotel walk to restaurants and shopping"

  • سلسلة استعلام المتجه: "quintessential lodging near running trails, eateries, retail" (موجهة إلى تمثيل رياضي)

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

تبدأ الأمثلة التالية باستعلام متجه أساسي وتضيف تدريجيا فلاتر، وبحث في الكلمات المفتاحية، وإعادة ترتيب دلالي.

searchSingle.ts يوضح سيناريو أساسي حيث تريد العثور على أوصاف مستندات تتطابق بشكل وثيق مع سلسلة استعلام المتجه. يقوم الكائن VectorQuery بتكوين البحث المتجه:

  • kNearestNeighborsCount يحد من عدد النتائج التي يتم إرجاعها بناء على تشابه المتجهات.
  • fields يحدد الحقل المتجه الذي يجب البحث ضده.
const vectorQuery: VectorQuery<HotelDocument> = {
    vector: vector,
    kNearestNeighborsCount: 5,
    fields: ["DescriptionVector"],
    kind: "vector",
    exhaustive: true
};

const searchOptions: SearchOptions<HotelDocument> = {
    top: 7,
    select: ["HotelId", "HotelName", "Description", "Category", "Tags"] as const,
    includeTotalCount: true,
    vectorSearchOptions: {
        queries: [vectorQuery],
        filterMode: "postFilter"
    }
};

const results: SearchDocumentsResult<HotelDocument> = await searchClient.search("*", searchOptions);

for await (const result of results.results) {
    const doc = result.document;
    console.log(`HotelId: ${doc.HotelId}, HotelName: ${doc.HotelName}, Score: ${result.score}`);
}

البحث باتجاه واحد باستخدام مرشح

في Azure AI Search، ينطبق filters على الحقول غير المتجهية في الفهرس. searchSingleWithFilter.ts فلاتر في Tags الملعب لتصفية أي فنادق لا توفر واي فاي مجاني.

const searchOptions: SearchOptions<HotelDocument> = {
    top: 7,
    select: ["HotelId", "HotelName", "Description", "Category", "Tags"] as const,
    includeTotalCount: true,
    filter: "Tags/any(tag: tag eq 'free wifi')", // Adding filter for "free wifi" tag
    vectorSearchOptions: {
        queries: [vectorQuery],
        filterMode: "postFilter"
    }
};

const results: SearchDocumentsResult<HotelDocument> = await searchClient.search("*", searchOptions);

البحث باتجاه واحد باستخدام مرشح جغرافي

يمكنك تحديد مرشح جغرافي مكاني لتقييد النتائج بمنطقة جغرافية محددة. searchSingleWithGeoFilter.ts يحدد نقطة جغرافية (واشنطن العاصمة، باستخدام إحداثيات خطوط الطول وخط العرض) ويعيد الفنادق ضمن 300 كيلومتر. تحدد هذه الخاصية filterMode متى يعمل المرشح. في هذه الحالة، postFilter يتم تشغيل المرشح بعد البحث المتجه.

const searchOptions: SearchOptions<HotelDocument> = {
    top: 5,
    includeTotalCount: true,
    select: ["HotelId", "HotelName", "Category", "Description", "Address/City", "Address/StateProvince"] as const,
    facets: ["Address/StateProvince"],
    filter: "geo.distance(Location, geography'POINT(-77.03241 38.90166)') le 300",
    vectorSearchOptions: {
        queries: [vectorQuery],
        filterMode: "postFilter"
    }
};

يجمع البحث الهجين بين استعلامات النص الكامل والاستعلامات المتجهية في طلب واحد. searchHybrid.ts يشغل كلا نوعي الاستعلام في نفس الوقت، ثم يستخدم دمج الترتيب المتبادل (RRF) لدمج النتائج في تصنيف موحد. يستخدم RRF عكس ترتيب النتائج من كل مجموعة نتائج لإنتاج تصنيف مدمج. لاحظ أن درجات البحث الهجين أصغر بشكل موحد من درجات الاستعلام الفردي.

const vectorQuery: VectorQuery<HotelDocument> = {
    vector: vector,
    kNearestNeighborsCount: 5,
    fields: ["DescriptionVector"],
    kind: "vector",
    exhaustive: true
};

const searchOptions: SearchOptions<HotelDocument> = {
    top: 5,
    includeTotalCount: true,
    select: ["HotelId", "HotelName", "Description", "Category", "Tags"] as const,
    vectorSearchOptions: {
        queries: [vectorQuery],
        filterMode: "postFilter"
    }
};

// Use search text for keyword search (hybrid search = vector + keyword)
const searchText = "historic hotel walk to restaurants and shopping";
const results: SearchDocumentsResult<HotelDocument> = await searchClient.search(searchText, searchOptions);

searchSemanticHybrid.ts يظهر التصنيف الدلالي، الذي يعيد ترتيب النتائج بناء على فهم اللغة.

const searchOptions: SearchOptions<HotelDocument> = {
    top: 5,
    includeTotalCount: true,
    select: ["HotelId", "HotelName", "Category", "Description"] as const,
    queryType: "semantic" as const,
    semanticSearchOptions: {
        configurationName: "semantic-config"
    },
    vectorSearchOptions: {
        queries: [vectorQuery],
        filterMode: "postFilter"
    }
};

const searchText = "historic hotel walk to restaurants and shopping";
const results: SearchDocumentsResult<HotelDocument> = await searchClient.search(searchText, searchOptions);

for await (const result of results.results) {
    console.log(`Score: ${result.score}, Re-ranker Score: ${result.rerankerScore}`);
}

قارن هذه النتائج مع نتائج البحث الهجينة من الاستعلام السابق. بدون إعادة ترتيب دلالية، يحتل فندق سوبلايم بالاس المرتبة الأولى لأن دمج الترتيب المتبادل (RRF) يجمع بين درجات النص والمتجه لإنتاج نتيجة مدمجة. بعد إعادة ترتيب دلالية، ينتقل فندق Swirling Currents إلى الصدارة.

يستخدم المصنف الدلالي نماذج فهم الآلة لتقييم مدى توافق كل نتيجة مع نية الاستعلام. وصف فندق التيارات الدوامة يذكر "walking access to shopping, dining, entertainment and the city center"، وهذا يتوافق بشكل وثيق مع استعلام "walk to restaurants and shopping"البحث . هذا التوافق الدلالي في تناول الطعام والتسوق القريب يرفعه فوق فندق سوبلايم بالاس، الذي لا يركز على المرافق القابلة للمشي في وصفه.

المسارات الرئيسية:

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

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

تنظيف الموارد

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

في بوابة Azure، اختر All resources أو Resource groups من اللوحة اليسرى للعثور على الموارد وإدارتها. يمكنك حذف الموارد بشكل فردي أو حذف مجموعة الموارد لإزالة كل الموارد دفعة واحدة.

وإلا، شغل الأمر التالي لحذف الفهرس الذي أنشأته في هذا البدء السريع.

npm run build && node -r dotenv/config dist/deleteIndex.js

في هذه البداية السريعة، تستخدم واجهات برمجة التطبيقات Azure AI Search REST لإنشاء وتحميل واستعلام <فهرس المتجه c1>vector.

في Azure AI Search، يحتوي مؤشر المتجهات على مخطط فهرس يحدد الحقول المتجهية وغير المتجهية، وتكوين بحث متجهات للخوارزميات التي تنشئ مساحة التضمين، وإعدادات على تعريفات الحقول المتجهية التي يتم تقييمها عند وقت الاستعلام. الفهارس - إنشاء أو تحديث (REST API) ينشئ فهرس المتجه.

تلميح

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

تكوين الوصول

قبل أن تبدأ، تأكد من أن لديك صلاحيات للوصول إلى المحتوى والعمليات في Azure AI Search. يستخدم هذا البدء السريع معرف Microsoft Entra ID للمصادقة والوصول القائم على الأدوار للتفويض. يجب أن تكون Owner أو User Access Administrator لتعيين الأدوار. إذا لم تكن الأدوار ممكنة، فاستخدم المصادقة المستندة إلى المفتاح بدلا من ذلك.

لتكوين الوصول الموصى به المستند إلى الدور:

  1. فعل access المعتمدة على الأدوار search service.

  2. قم بتعيين الأدوار التالية لحساب المستخدم الخاص بك.

    • Search Service المساهم

    • مساهم بيانات فهرس البحث

    • قارئ بيانات فهرس البحث

الحصول على نقطة النهاية

كل خدمة Azure AI Search لديها endpoint، وهو رابط فريد يحدد ويوفر الوصول إلى الشبكة للخدمة. في قسم لاحق، تحدد هذه النقطة النهائية للاتصال بخدمة البحث الخاصة بك بشكل برمجي.

للحصول على نقطة النهاية:

  1. انتقل إلى خدمة البحث في مدخل Microsoft Azure.

  2. من الجزء الأيمن، حدد نظرة عامة.

  3. دون نقطة النهاية، والتي يجب أن تبدو https://my-service.search.windows.net.

إعداد البيئة

  1. استخدم Git لاستنساخ مستودع العينات.

    git clone https://github.com/Azure-Samples/azure-search-rest-samples

  2. انتقل إلى مجلد البدء السريع وافتحه في Visual Studio Code.

    cd azure-search-rest-samples/Quickstart-vectors
code .

  3. في az-search-quickstart-vectors.rest، استبدل قيمة البديل المؤقت ل @baseUrl بعنوان URL الذي حصلت عليه في Get endpoint.

  4. للمصادقة بدون مفتاح باستخدام Microsoft Entra ID، سجل الدخول إلى حسابك في Azure. إذا كان لديك عدة اشتراكات، اختر الاشتراك الذي يحتوي على خدمة Azure AI Search الخاصة بك.

    az login

  5. للمصادقة بدون مفتاح باستخدام Microsoft Entra ID، قم بإنشاء رمز وصول.

    az account get-access-token --scope https://search.azure.com/.default --query accessToken -o tsv

  6. استبدل قيمة التبديل المؤقت ل @token بالرمز من الخطوة السابقة.

تشغيل التعليمات البرمجية

  1. تحت ### List existing indexes by name، اختر إرسال طلب للتحقق من اتصالك.

    يجب أن تظهر استجابة في جزء مجاور. إذا كان لديك فهارس موجودة، يتم سردها. وإلا، تكون القائمة فارغة. إذا كان رمز HTTP هو 200 OK، فأنت جاهز للمتابعة.

  2. أرسل الطلبات المتبقية بشكل متسلسل لإنشاء فهرس متجه، ورفع المستندات، وتشغيل أنواع مختلفة من استعلامات المتجه.

الاخراج

كل طلب استعلام يعطي نتائج JSON. المثال التالي هو مخرج ### Run a single vector query الطلب، الذي يعرض نتائج البحث المتجهة مرتبة حسب درجة التشابه.

{
  "@odata.count": 5,
  "value": [
    {
      "@search.score": 0.6605852,
      "HotelId": "48",
      "HotelName": "Nordick's Valley Motel",
      "Description": "Only 90 miles (about 2 hours) from the nation's capital and nearby most everything the historic valley has to offer. Hiking? Wine Tasting? Exploring the caverns? It's all nearby and we have specially priced packages to help make our B&B your home base for fun while visiting the valley.",
      "Category": "Boutique",
      "Tags": [
        "continental breakfast",
        "air conditioning",
        "free wifi"
      ]
    },
    {
      "@search.score": 0.6333684,
      "HotelId": "13",
      "HotelName": "Luxury Lion Resort",
      "Description": "Unmatched Luxury. Visit our downtown hotel to indulge in luxury accommodations. Moments from the stadium and transportation hubs, we feature the best in convenience and comfort.",
      "Category": "Luxury",
      "Tags": [
        "bar",
        "concierge",
        "restaurant"
      ]
    },
    {
      "@search.score": 0.605672,
      "HotelId": "4",
      "HotelName": "Sublime Palace Hotel",
      "Description": "Sublime Palace Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience.",
      "Category": "Boutique",
      "Tags": [
        "concierge",
        "view",
        "air conditioning"
      ]
    },
    {
      "@search.score": 0.6026341,
      "HotelId": "49",
      "HotelName": "Swirling Currents Hotel",
      "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs.",
      "Category": "Suite",
      "Tags": [
        "air conditioning",
        "laundry service",
        "24-hour front desk service"
      ]
    },
    {
      "@search.score": 0.57902366,
      "HotelId": "2",
      "HotelName": "Old Century Hotel",
      "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.",
      "Category": "Boutique",
      "Tags": [
        "pool",
        "free wifi",
        "air conditioning",
        "concierge"
      ]
    }
  ]
}

فهم الكود

ملاحظة

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

الآن بعد أن قمت بتشغيل التعليمات البرمجية ، دعنا نقسم الخطوات الرئيسية:

  1. إنشاء فهرس متجه
  2. تحميل المستندات إلى الفهرس
  3. استعلام الفهرس

إنشاء فهرس متجه

قبل أن تضيف المحتوى إلى Azure AI Search، يجب عليك إنشاء فهرس لتحديد كيفية تخزين وهيكلة المحتوى. هذا البدء السريع يستدعي Indexes - Create (واجهة برمجة تطبيقات REST) لبناء فهرس متجه مسمى hotels-vector-quickstart وهياكل بياناته الفيزيائية على خدمة البحث الخاصة بك.

مخطط الفهرس منظم حول محتوى الفنادق. تتكون بيانات العينة من أوصاف متجهة وغير عاملة للفنادق الوهمية. يظهر المقتطف التالي الهيكل الرئيسي للطلب ### Create a new index .

PUT {{baseUrl}}/indexes/hotels-vector-quickstart?api-version={{api-version}}  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "name": "hotels-vector-quickstart",
    "fields": [
        { "name": "HotelId", "type": "Edm.String", "key": true, "filterable": true },
        { "name": "HotelName", "type": "Edm.String", "searchable": true },
        { "name": "Description", "type": "Edm.String", "searchable": true },
        {
            "name": "DescriptionVector",
            "type": "Collection(Edm.Single)",
            "searchable": true,
            "dimensions": 1536,
            "vectorSearchProfile": "my-vector-profile"
        },
        { "name": "Category", "type": "Edm.String", "filterable": true, "facetable": true },
        { "name": "Tags", "type": "Collection(Edm.String)", "filterable": true, "facetable": true }
        // Additional fields omitted for brevity
    ],
    "vectorSearch": {
        "algorithms": [
            { "name": "hnsw-vector-config", "kind": "hnsw" }
        ],
        "profiles": [
            { "name": "my-vector-profile", "algorithm": "hnsw-vector-config" }
        ]
    },
    "semantic": {
        "configurations": [
            {
                "name": "semantic-config",
                "prioritizedFields": {
                    "titleField": { "fieldName": "HotelName" },
                    "prioritizedContentFields": [{ "fieldName": "Description" }]
                }
            }
        ]
    }
}

المسارات الرئيسية:

  • يدعم هذا الفهرس تحديدا قدرات بحث متعددة:

  • يجب أن تتطابق الخاصية dimensions مع حجم مخرج نموذج التضمين الخاص بك. يستخدم هذا البدء السريع 1,536 بعدا ليتناسب مع النموذج text-embedding-ada-002 .

  • يحدد هذا vectorSearch القسم خوارزمية أقرب جار تقريبي (ANN). تشمل الخوارزميات المدعومة العالم الصغير القابل للملاحة الهرمي (HNSW) والجار الشامل K-أقرب جار (KNN). لمزيد من المعلومات، راجع الصلة في البحث المتجه.

تحميل المستندات إلى الفهرس

الفهارس التي تم إنشاؤها حديثا فارغة. لتعبئة فهرس وجعله قابلا للبحث، يجب تحميل مستندات JSON التي تتوافق مع مخطط الفهرس.

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

هذا البدء السريع يستدعي Documents - Index (واجهة برمجة تطبيقات REST) لإضافة نماذج مستندات الفنادق إلى الفهرس الخاص بك. يظهر المقتطف التالي هيكل الطلب ### Upload 7 documents .

POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/index?api-version={{api-version}}  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "value": [
        {
            "@search.action": "mergeOrUpload",
            "HotelId": "1",
            "HotelName": "Stay-Kay City Hotel",
            "Description": "This classic hotel is ideally located on the main commercial artery of the city...",
            "DescriptionVector": [-0.0347, 0.0289, ... ],  // 1536 floats
            "Category": "Boutique",
            "Tags": ["view", "air conditioning", "concierge"],
            "ParkingIncluded": false,
            "Rating": 3.60,
            "Address": { "City": "New York", "StateProvince": "NY" },
            "Location": { "type": "Point", "coordinates": [-73.975403, 40.760586] }
        }
        // Additional documents omitted for brevity
    ]
}

المسارات الرئيسية:

  • يمثل كل مستند في value الصفيف فندقا ويحتوي على حقول تطابق مخطط الفهرس. @search.action تحدد المعلمة العملية التي يجب تنفيذها لكل مستند. تستخدم mergeOrUploadهذه البداية السريعة ، التي تضيف المستند إذا لم يكن موجودا أو تحدث المستند إذا كان موجودا.

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

استعلام الفهرس

تظهر الاستعلامات في ملف العينة أنماط بحث مختلفة. تستند استعلامات المتجهات النموذجية إلى سلسلتين:

  • سلسلة بحث كاملة النص: "historic hotel walk to restaurants and shopping"

  • سلسلة استعلام المتجه: "quintessential lodging near running trails, eateries, retail" (موجهة إلى تمثيل رياضي)

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

تبدأ الأمثلة التالية باستعلام متجه أساسي وتضيف تدريجيا فلاتر، وبحث في الكلمات المفتاحية، وإعادة ترتيب دلالي.

يوضح الطلب ### Run a single vector query سيناريو أساسي حيث تريد العثور على أوصاف المستندات التي تطابق بشكل كبير سلسلة استعلام المتجه. تقوم المصفوفة vectorQueries بتكوين البحث المتجه:

  • k يحد من عدد النتائج التي يتم إرجاعها بناء على تشابه المتجهات.
  • fields يحدد الحقل المتجه الذي يجب البحث ضده.
POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search?api-version={{api-version}}  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "count": true,
    "select": "HotelId, HotelName, Description, Category, Tags",
    "vectorQueries": [
        {
            "vector": [ ... ],  // 1536-dimensional vector of "quintessential lodging near running trails, eateries, retail"
            "k": 5,
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true
        }
    ]
}

البحث باتجاه واحد باستخدام مرشح

في Azure AI Search، ينطبق filters على الحقول غير المتجهية في الفهرس. يقوم الطلب ### Run a vector query with a filter بتصفية الساحة Tags لتصفية أي فنادق لا توفر واي فاي مجاني.

POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search?api-version={{api-version}}  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "count": true,
    "select": "HotelId, HotelName, Description, Category, Tags",
    "filter": "Tags/any(tag: tag eq 'free wifi')",
    "vectorFilterMode": "postFilter",
    "vectorQueries": [
        {
            "vector": [ ... ],  // 1536-dimensional vector
            "k": 7,
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true
        }
    ]
}

البحث باتجاه واحد باستخدام مرشح جغرافي

يمكنك تحديد مرشح جغرافي مكاني لتقييد النتائج بمنطقة جغرافية محددة. يحدد الطلب ### Run a vector query with a geo filter نقطة جغرافية (واشنطن العاصمة، باستخدام إحداثيات خطوط الطول والعرض) ويعيد الفنادق ضمن 300 كيلومتر. يحدد المعامل vectorFilterMode متى يعمل الفلتر. في هذه الحالة، postFilter يتم تشغيل المرشح بعد البحث المتجه.

POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search?api-version={{api-version}}  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "count": true,
    "select": "HotelId, HotelName, Address/City, Address/StateProvince, Description",
    "filter": "geo.distance(Location, geography'POINT(-77.03241 38.90166)') le 300",
    "vectorFilterMode": "postFilter",
    "top": 5,
    "facets": [ "Address/StateProvince"],
    "vectorQueries": [
        {
            "vector": [ ... ],  // 1536-dimensional vector
            "k": 5,
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true
        }
    ]
}

يجمع البحث الهجين بين استعلامات النص الكامل والاستعلامات المتجهية في طلب واحد. يقوم الطلب ### Run a hybrid query بتشغيل كلا نوعي الاستعلام في نفس الوقت، ثم يستخدم دمج الترتيب المتبادل (RRF) لدمج النتائج في ترتيب موحد. يستخدم RRF عكس ترتيب النتائج من كل مجموعة نتائج لإنتاج تصنيف مدمج. لاحظ أن درجات البحث الهجين أصغر بشكل موحد من درجات الاستعلام الفردي.

POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search?api-version={{api-version}}  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "count": true,
    "search": "historic hotel walk to restaurants and shopping",
    "select": "HotelId, HotelName, Category, Tags, Description",
    "top": 5,
    "vectorQueries": [
        {
            "vector": [ ... ],  // 1536-dimensional vector
            "k": 5,
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true
        }
    ]
}

يظهر الطلب ### Run a hybrid query with semantic rerankingالترتيب الدلالي، الذي يعيد ترتيب النتائج بناء على فهم اللغة.

POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search?api-version={{api-version}}  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "count": true,
    "search": "historic hotel walk to restaurants and shopping",
    "select": "HotelId, HotelName, Category, Description",
    "queryType": "semantic",
    "semanticConfiguration": "semantic-config",
    "top": 5,
    "vectorQueries": [
        {
            "vector": [ ... ],  // 1536-dimensional vector
            "k": 7,
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true
        }
    ]
}

قارن هذه النتائج مع نتائج البحث الهجينة من الاستعلام السابق. بدون إعادة ترتيب دلالية، يحتل فندق سوبلايم بالاس المرتبة الأولى لأن دمج الترتيب المتبادل (RRF) يجمع بين درجات النص والمتجه لإنتاج نتيجة مدمجة. بعد إعادة ترتيب دلالية، ينتقل فندق Swirling Currents إلى الصدارة.

يستخدم المصنف الدلالي نماذج فهم الآلة لتقييم مدى توافق كل نتيجة مع نية الاستعلام. وصف فندق التيارات الدوامة يذكر "walking access to shopping, dining, entertainment and the city center"، وهذا يتوافق بشكل وثيق مع استعلام "walk to restaurants and shopping"البحث . هذا التوافق الدلالي في تناول الطعام والتسوق القريب يرفعه فوق فندق سوبلايم بالاس، الذي لا يركز على المرافق القابلة للمشي في وصفه.

المسارات الرئيسية:

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

تنظيف الموارد

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

في بوابة Azure، اختر All resources أو Resource groups من اللوحة اليسرى للعثور على الموارد وإدارتها. يمكنك حذف الموارد بشكل فردي أو حذف مجموعة الموارد لإزالة كل الموارد دفعة واحدة.

وإلا، يمكنك إرسال ### Delete an index طلب حذف الفهرس الذي أنشأته في هذه البداية السريعة.

المحتويات ذات الصلة

  • Last updated on