JavaScript için Azure AI Search istemci kitaplığı - sürüm 12.1.0

  • Makale

Azure AI Search (eski adıyla "Azure Bilişsel Arama"), geliştiricilerin büyük dil modellerini kurumsal verilerle birleştiren zengin arama deneyimleri ve üretken yapay zeka uygulamaları oluşturmalarına yardımcı olan yapay zeka destekli bir bilgi alma platformudur.

Azure AI Search hizmeti aşağıdaki uygulama senaryoları için uygundur:

  • Çeşitli içerik türlerini tek bir aranabilir dizinde birleştirin. Dizini doldurmak için içeriğinizi içeren JSON belgelerini gönderebilirsiniz veya verileriniz zaten Azure'daysa verileri otomatik olarak çekmek için bir dizin oluşturucu oluşturabilirsiniz.
  • Resimlerden ve yapılandırılmamış belgelerden aranabilir içerik oluşturmak için dizin oluşturucuya beceri kümeleri ekleyin. Beceri kümesi yerleşik OCR, varlık tanıma, anahtar ifade ayıklama, dil algılama, metin çevirisi ve yaklaşım analizi için Azure AI Services API'lerinden yararlanıyor. Ayrıca, veri alımı sırasında içeriğinizin dış işlemesini tümleştirmek için özel beceriler de ekleyebilirsiniz.
  • Bir arama istemcisi uygulamasında, ticari web arama motorlarına ve sohbet stili uygulamalara benzer sorgu mantığı ve kullanıcı deneyimleri uygulayın.

@azure/search-documents istemci kitaplığını kullanarak:

  • Vektör, anahtar sözcük ve karma sorgu formlarını kullanarak sorgu gönderin.
  • Meta veriler, jeo-uzamsal arama, yönlü gezinti veya filtre ölçütlerine göre sonuçları daraltmak için filtrelenmiş sorgular uygulayın.
  • Arama dizinleri oluşturma ve yönetme.
  • Arama dizininde belgeleri karşıya yükleyin ve güncelleştirin.
  • Azure'dan dizine veri çeken dizin oluşturucular oluşturun ve yönetin.
  • Veri alımına yapay zeka zenginleştirmesi ekleyen beceri kümeleri oluşturun ve yönetin.
  • Gelişmiş metin analizi veya çok dilli içerik için çözümleyiciler oluşturun ve yönetin.
  • İş mantığını veya yeniliği dikkate almak için anlamsal derecelendirme ve puanlama profilleri aracılığıyla sonuçları iyileştirin.

Önemli bağlantılar:

Başlarken

@azure/search-documents paketini yükleme

npm install @azure/search-documents

Şu anda desteklenen ortamlar

  • Node.js LTS sürümleri
  • Safari, Chrome, Microsoft Edge ve Firefox'un en son sürümleri.

Daha fazla bilgi için bkz. destek ilkesi.

Önkoşullar

Yeni bir arama hizmeti oluşturmak için Azure portal, Azure PowerShellveya Azure CLIkullanabilirsiniz. Başlangıç için ücretsiz bir örnek oluşturmak için Azure CLI'yi kullanan bir örnek aşağıda verilmiştir:

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

Kullanılabilir seçenekler hakkında daha fazla bilgi için bkz. fiyatlandırma katmanı seçme .

İstemcinin kimliğini doğrulama

Arama hizmetiyle etkileşim kurmak için uygun istemci sınıfının bir örneğini oluşturmanız gerekir: dizinlenmiş belgelerde arama yapmak için SearchClient, dizinleri yönetmek için SearchIndexClient veya veri kaynaklarında gezinmek ve arama belgelerini dizine yüklemek için SearchIndexerClient. İstemci nesnesinin örneğini oluşturmak için bir uç nokta ve Azure rolleri veya API anahtarıgerekir. Arama hizmetiyle desteklenen kimlik doğrulama yaklaşımları hakkında daha fazla bilgi için belgelere başvurabilirsiniz.

API Anahtarı Alma

Api anahtarı, önceden var olan rol atamaları gerektirmediğinden başlangıç olarak daha kolay bir yaklaşım olabilir.

Azure portalarama hizmetinden uç noktası ve API anahtarı alabilirsiniz. API anahtarı alma yönergeleri için lütfen belgelerine bakın.

Alternatif olarak, arama hizmetinden API anahtarını almak için aşağıdaki Azure CLI komutunu kullanabilirsiniz:

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

Arama hizmetinize erişmek için kullanılan iki tür anahtar vardır: yönetici(okuma-yazma) ve sorgu(salt okunur) anahtarları . İstemci uygulamalarında erişimi ve işlemleri kısıtlamak, hizmetinizdeki arama varlıklarını korumak için gereklidir. İstemci uygulamasından kaynaklanan tüm sorgular için her zaman yönetici anahtarı yerine sorgu anahtarı kullanın.

Not: Yukarıdaki örnek Azure CLI kod parçacığı, API'leri keşfetmeye başlamanın daha kolay olması için bir yönetici anahtarı alır, ancak dikkatli bir şekilde yönetilmelidir.

Bir api anahtarına sahip olduktan sonra, bunu aşağıdaki gibi kullanabilirsiniz:

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

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

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

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

Ulusal Bulutta kimlik doğrulaması

Ulusal Bulutkimlik doğrulaması yapmak için istemci yapılandırmanıza aşağıdaki eklemeleri yapmanız gerekir:

  • SearchClientOptions'da Audience ayarlama
const {
  SearchClient,
  SearchIndexClient,
  SearchIndexerClient,
  AzureKeyCredential,
  KnownSearchAudience,
} = require("@azure/search-documents");

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

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

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

Temel kavramlar

Azure AI Search hizmeti, aranabilir verilerin JSON belgeleri biçiminde kalıcı olarak depolanmasını sağlayan bir veya daha fazla dizin içerir. (Arama konusunda yeniyseniz, dizinler ve veritabanı tabloları arasında çok kaba bir benzetme yapabilirsiniz.)@azure/search-documents istemci kitaplığı bu kaynaklardaki işlemleri üç ana istemci türü aracılığıyla kullanıma sunar.

Not: Çağırdığı API'ler Çıkış Noktaları Arası Kaynak Paylaşımı (CORS) desteğine sahip olmadığından bu istemciler tarayıcıda çalışamaz.

TypeScript/JavaScript'e özgü kavramlar

Evrak

Arama dizininde depolanan bir öğe. Bu belgenin şekli dizinde fields özelliği kullanılarak açıklanmıştır. Her SearchField bir adı, veri türü ve aranabilir veya filtrelenebilir olması gibi ek meta veriler vardır.

Sayfalandırma

Genellikle bir kullanıcıya arama sonuçlarının yalnızca bir alt kümesini bir kerede göstermek isteyebilirsiniz. Bunu desteklemek için top, skip ve includeTotalCount parametrelerini kullanarak arama sonuçlarının üzerine sayfalanmış bir deneyim sağlayabilirsiniz.

Belge alanı kodlaması

Bir dizinde desteklenen veri türleri API isteklerindeki/yanıtlarındaki JSON türleriyle eşlenir. JS istemci kitaplığı, bazı özel durumlar dışında bunları çoğunlukla aynı tutar:

  • Edm.DateTimeOffset bir JS Datedönüştürülür.
  • Edm.GeographyPoint, istemci kitaplığı tarafından dışarı aktarılan bir GeographyPoint türüne dönüştürülür.
  • number türünün (NaN, Infinity, -Infinity) özel değerleri REST API'de dize olarak serileştirilir, ancak istemci kitaplığı tarafından number geri dönüştürülür.

Not: Veri türleri, dizin şemasındaki alan türüne değil değere göre dönüştürülür. Bu, bir alanın değeri olarak bir ISO8601 Tarih dizeniz (örneğin, "2020-03-06T18:48:27.896Z") varsa, şemanızda nasıl depoladığınıza bakılmaksızın tarihe dönüştürüleceği anlamına gelir.

Örnekler

Aşağıdaki örneklerde temel bilgiler gösterilmektedir. Lütfen daha fazlası için örnek göz atın.

Dizin Oluşturma

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

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

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

  console.log(result);
}

main();

Dizinden belirli bir belgeyi alma

Belirli bir belge birincil anahtar değeri tarafından alınabilir:

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

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

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

main();

Dizine belge ekleme

Bir toplu iş içinde dizine birden çok belge yükleyebilirsiniz:

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

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

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

main();

Belgeler üzerinde arama yapma

Belirli bir sorgunun tüm sonuçlarını listelemek için searchbasit sorgu söz dizimi kullanan bir arama dizesiyle kullanabilirsiniz:

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

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

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

main();

Lucene söz dizimi kullanan daha gelişmiş bir arama için olacak belirtin:

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

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

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

main();

TypeScript ile sorgulama

TypeScript'te, SearchClient dizin belgelerinizin model şekli olan genel bir parametre alır. Bu, sonuçlarda döndürülen alanların kesin olarak türlenmiş aramasını gerçekleştirmenizi sağlar. TypeScript, select parametresini belirtirken döndürülen alanları da denetleyebilir.

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

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

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

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

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

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

main();

OData filtreleri ile sorgulama

sorgu parametresini kullanmak,OData $filter ifadesinin söz dizimini kullanarak bir dizini sorgulamanıza olanak tanır.

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

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

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

main();

Vektörlerle sorgulama

Metin ekleme işlemleri, vector arama parametresi kullanılarak sorgulanabilir. Daha fazla bilgi için bkz. Sorgu vektörleri ve filtre vektör sorguları .

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

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

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

main();

Modellerle sorgulama

Model, uygulamanızın kullanıcısının önceden yapılandırılmış boyutlar boyunca aramayı iyileştirmesine yardımcı olmak için kullanılır. model söz dizimi model değerlerini sıralama ve demet seçenekleri sağlar.

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

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

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

main();

Sonuçlar alınırken, her model demetine giren sonuçların sayısını belirten bir facets özelliği kullanılabilir. Bu, iyileştirmeyi yönlendirmek için kullanılabilir (örneğin, 3'ten büyük veya 3'e eşit ve 4'ten küçük olan Rating filtreleyen bir izleme araması yapmak.)

Sorun giderme

Günlük tutmak

Günlüğün etkinleştirilmesi, hatalarla ilgili yararlı bilgilerin ortaya çıkmasına yardımcı olabilir. HTTP isteklerinin ve yanıtlarının günlüğünü görmek için AZURE_LOG_LEVEL ortam değişkenini infoolarak ayarlayın. Alternatif olarak, @azure/loggersetLogLevel çağrılarak günlükler çalışma zamanında etkinleştirilebilir:

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

setLogLevel("info");

Günlükleri etkinleştirme hakkında daha ayrıntılı yönergeler için@azure/günlükçü paketi belgelerine bakabilirsiniz.

Sonraki adımlar

Katkıda

Bu kitaplığa katkıda bulunmak istiyorsanız kodu oluşturma ve test etme hakkında daha fazla bilgi edinmek için lütfen katkıda bulunma kılavuzu okuyun.

Bu proje katkıları ve önerileri memnuniyetle karşılar. Çoğu katkı, Katkıda Bulunan Lisans Sözleşmesi'ni (CLA) kabul ederek bize katkınızı kullanma hakları verme hakkına sahip olduğunuzu bildirmenizi gerektirir. Ayrıntılar için cla.microsoft.comadresini ziyaret edin.

Bu proje, Microsoft Açık Kaynak Kullanım Kurallarıbenimsemiştir. Daha fazla bilgi için bkz. Davranış Kuralları SSS veya ek sorularınız veya yorumlarınızla opencode@microsoft.com iletişime geçin.

  • JavaScript için Microsoft Azure SDK

Gösterimler