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

  • Makale

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

Azure AI Search, 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 büyük metin belgelerinden aranabilir içerik oluşturmak için bir 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 yapay zeka hizmetlerinden api'lerden 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 altyapılarına benzer sorgu mantığını ve kullanıcı deneyimlerini 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, çok yönlü gezinti için veya filtre ölçütlerine göre sonuçları daraltmak için filtrelenmiş sorgular uygulayın.
  • Arama dizinleri oluşturma ve yönetme.
  • Arama dizinindeki 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 güncelliği dikkate almak için puanlama profilleri aracılığıyla sonuçları iyileştirin.

Önemli bağlantılar:

Başlarken

@azure/search-documents paketini yükleyin

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, Azure PowerShell veya Azure CLI'yı kullanabilirsiniz. Başlamak için ücretsiz bir örnek oluşturmak için Azure CLI'yi kullanan bir örnek aşağıda verilmişti:

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: SearchClient dizinlenmiş belgelerde arama yapmak, SearchIndexClient dizinleri yönetmek veya SearchIndexerClient veri kaynaklarında gezinmek ve arama belgelerini bir dizine yüklemek için.

İstemci nesnesinin örneğini oluşturmak için bir uç nokta 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'daki arama hizmetinden alabilirsiniz. API anahtarı alma yönergeleri için lütfen belgelere bakın.

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

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

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 Bulutta kimlik doğrulaması yapmak için istemci yapılandırmanıza aşağıdaki eklemeleri yapmanız gerekir:

  • şu ayarı ayarlayın:AudienceSearchClientOptions
const {
  SearchClient,
  SearchIndexClient,
  SearchIndexerClient,
  AzureKeyCredential,
  KnownSearchAudience,
} = require("@azure/search-documents");

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

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

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

Önemli kavramlar

Azure AI Arama hizmeti, aranabilir verilerin JSON belgeleri biçiminde kalıcı olarak depolanmasını sağlayan bir veya daha fazla dizin içerir. (Aramada yeniyseniz, dizinler ve veritabanı tabloları arasında çok kaba bir benzetme yapabilirsiniz.) İstemci kitaplığı, @azure/search-documents üç ana istemci türü aracılığıyla bu kaynaklar üzerindeki işlemleri 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

Belgeler

Arama dizininde depolanan bir öğe. Bu belgenin şekli, s kullanılarak Fielddizinde açıklanmıştır. Her Alanın bir adı, veri türü ve aranabilir veya filtrelenebilir olması gibi ek meta veriler vardır.

Sayfalandırma

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

Belge alanı kodlama

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 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ün number özel değerleri (NaN, Infinity, -Infinity) REST API'de dize olarak serileştirilir, ancak istemci kitaplığı tarafından öğesine geri number 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, bu dizenin ş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. Daha fazla bilgi için lütfen örneklerimize 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çindeki 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();

Belgelerde arama yapma

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

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 fullolarak belirtinqueryType:

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 belirlenmiş aramasını gerçekleştirmenizi sağlar. TypeScript ayrıca parametre select belirtirken döndürülen alanları denetleyebiliyor.

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

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

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

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

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

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

main();

OData filtreleri ile sorgulama

sorgu parametresini filter 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 arama parametresi kullanılarak vector sorgulanabilir.

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

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

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

main();

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 düşen sonuç sayısını gösteren bir facets özellik 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 öğeyi filtreleyen Rating bir izleme araması yapmak.)

Sorun giderme

Günlüğe Kaydetme

Günlüğe kaydetmenin etkinleştirilmesi hatalarla ilgili yararlı bilgilerin ortaya çıkarılması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, günlüğü çalışma zamanında içinde çağrılarak setLogLevel@azure/loggeretkinleş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 bulunma

Bu kitaplığa katkıda bulunmak isterseniz, kodu derleme ve test etme hakkında daha fazla bilgi edinmek için lütfen katkıda bulunma kılavuzunu okuyun.

Bu proje, katkı ve önerilere açıktır. Çoğu durumda, sağladığınız katkıyı kullanmamız için bize hak tanıma hakkına sahip olduğunuzu ve bu hakkı bize tanıdığınızı bildiren bir Katkıda Bulunan Lisans Sözleşmesi’ni (CLA) kabul etmeniz gerekir. Ayrıntılar için cla.microsoft.com adresini ziyaret edin.

Bu proje Microsoft Açık Kaynak Kullanım Kuralları'nı benimsemiştir. Daha fazla bilgi için Kullanım Kuralları SSS bölümüne bakın veya ek sorularınız veya yorumlarınızla iletişime geçin opencode@microsoft.com .

İzlenimler