Aracılığıyla paylaş

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

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şturması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.

İstemci kitaplığını @azure/search-documents 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

Daha fazla ayrıntı için destek ilkemize bakın.

Önkoşullar

Yeni bir arama hizmeti oluşturmak için Azure portalını, Azure PowerShell'i veya Azure CLI'yı kullanabilirsiniz. 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 fiyatlandırma katmanı seçme bölümüne bakın.

İ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: SearchClient dizine alınmış belgeleri aramak, SearchIndexClient dizinleri yönetmek veya SearchIndexerClient veri kaynaklarını taramak ve arama belgelerini dizine yüklemek için. Bir istemci nesnesinin örneğini oluşturmak için bir uç noktaya ve Azure rollerine veya API anahtarına ihtiyacınız vardır. 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.

Uç noktayı ve API anahtarınıAzure portalındaki arama hizmetinden alabilirsiniz. API anahtarının nasıl alınacağına ilişkin talimatlar için lütfen belgelere bakın.

Alternatif olarak, API anahtarını arama hizmetinden 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: admin(okuma-yazma) ve query(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:

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

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

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

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

Ulusal Bulutta kimlik doğrulaması

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

  • Audience Girişi ayarlayınSearchClientOptions
import {
  SearchClient,
  AzureKeyCredential,
  KnownSearchAudience,
  SearchIndexClient,
  SearchIndexerClient,
} from "@azure/search-documents";

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

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

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

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.) İstemci @azure/search-documents kitaplığı, bu kaynaklar üzerindeki işlemleri üç ana istemci türü aracılığıyla kullanıma sunar.

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

TypeScript/JavaScript'e özgü kavramlar

Evrak

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

Sayfalandırma

Genellikle, bir kullanıcıya aynı anda yalnızca arama sonuçlarının bir alt kümesini göstermek istersiniz. Bunu desteklemek için, arama sonuçlarının en üstünde sayfalı bir deneyim sağlamak için ve topskip parametrelerini kullanabilirsinizincludeTotalCount.

Belge alanı kodlaması

Bir dizindeki 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 JS'ye Datedönüştürülür.
  • Edm.GeographyPoint istemci kitaplığı tarafından dışarı aktarılan bir GeographyPoint türe dönüştürülür.
  • Türündeki number özel değerler (NaN, Infinity, -Infinity) REST API'de dizeler olarak serileştirilir, ancak istemci kitaplığı tarafından yeniden number dönüştürülür.

Not: Veri türleri, dizin şemasındaki alan türüne göre 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 örnekler temel bilgileri göstermektedir - çok daha fazlası için lütfen örneklerimize göz atın .

Dizin Oluşturma

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

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

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

console.log(`Index created with name ${result.name}`);

Dizinden belirli bir belgeyi alma

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

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

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

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

Dizine belge ekleme

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

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

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

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

Belgeler üzerinde arama yapma

Belirli bir sorgunun tüm sonuçlarını listelemek için, search kullanan bir arama dizesi ile kullanabilirsiniz:

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

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

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

Lucene sözdizimini kullanan daha gelişmiş bir arama için şu şekilde queryTypebelirtinfull:

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

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

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

TypeScript 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, bir select parametre belirtirken döndürülen alanları da kontrol edebilir.

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

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

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

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

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

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

OData filtreleri ile sorgulama

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

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

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

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

Vektörlerle sorgulama

Metin katıştırmaları, search parametresi kullanılarak vector sorgulanabilir. Daha fazla bilgi için Vektörleri sorgulama ve Vektör sorgularını filtreleme başlıklı makaleleri inceleyin.

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

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

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

Modellerle sorgulama

Modeller , uygulamanızın bir kullanıcısının önceden yapılandırılmış boyutlar boyunca bir aramayı hassaslaştırmasına yardımcı olmak için kullanılır. Model sözdizimi , model değerlerini sıralama ve demetleme seçenekleri sağlar.

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

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

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

Sonuçlar alınırken, her model demetine düşen sonuçların sayısını gösteren bir facets özellik kullanılabilir. Bu, iyileştirmeyi teşvik etmek için kullanılabilir (örneğin, 3'ten büyük veya 3'e eşit ve 4'ten küçük olmayı filtreleyen Rating bir takip araması yayınlamak).

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 ortam değişkenini AZURE_LOG_LEVEL olarak infoayarlayın. Alternatif olarak, çalışma zamanında setLogLevel@azure/logger çağrılarak günlük tutma 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 isterseniz kodu oluşturma ve test etme hakkında daha fazla bilgi edinmek için lütfen katkıda bulunma kılavuzunu 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.com adresini ziyaret edin.

Bu projede Microsoft Açık Kaynak Kullanım Şartları kabul edilmiş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
  • Last updated on