Azure Cognitive Search pustaka klien untuk Python - versi 11.4.0

  • Artikel

Azure Cognitive Search adalah solusi cloud search-as-a-service yang memberi pengembang API dan alat untuk menambahkan pengalaman pencarian yang kaya melalui konten privat dan heterogen di aplikasi web, seluler, dan perusahaan.

Layanan Azure Cognitive Search sangat cocok untuk skenario aplikasi berikut:

  • Mengonsolidasikan berbagai jenis konten ke dalam satu indeks yang dapat dicari. Untuk mengisi indeks, Anda dapat mendorong dokumen JSON yang berisi konten Anda, atau jika data Anda sudah ada di Azure, buat pengindeks untuk menarik data secara otomatis.
  • Lampirkan set keterampilan ke pengindeks untuk membuat konten yang dapat dicari dari gambar dan dokumen teks besar. Set keterampilan memanfaatkan AI dari Cognitive Services untuk OCR bawaan, pengenalan entitas, ekstraksi frasa kunci, deteksi bahasa, terjemahan teks, dan analisis sentimen. Anda juga dapat menambahkan keterampilan kustom untuk mengintegrasikan pemrosesan eksternal konten Anda selama penyerapan data.
  • Dalam aplikasi klien pencarian, terapkan logika kueri dan pengalaman pengguna yang mirip dengan mesin pencari web komersial.

Gunakan pustaka klien Azure.Search.Documents untuk:

  • Kirim kueri untuk formulir kueri sederhana dan tingkat lanjut yang menyertakan pencarian fuzzy, pencarian kartubebas, ekspresi reguler.
  • Terapkan kueri yang difilter untuk navigasi tersaring, pencarian geospasial, atau untuk mempersempit hasil berdasarkan kriteria filter.
  • Membuat dan mengelola indeks pencarian.
  • Unggah dan perbarui dokumen dalam indeks pencarian.
  • Membuat dan mengelola pengindeks yang menarik data dari Azure ke dalam indeks.
  • Membuat dan mengelola set keterampilan yang menambahkan pengayaan AI ke penyerapan data.
  • Membuat dan mengelola penganalisis untuk analisis teks tingkat lanjut atau konten multibahasa.
  • Optimalkan hasil melalui profil penilaian untuk memperhitungkan logika bisnis atau kesegaran.

Kode sumber | Paket (PyPI) | Paket (Conda) | Dokumentasi | referensi APIDokumentasi | produkSampel

Memulai

Menginstal paket

Instal pustaka klien Azure Cognitive Search untuk Python dengan pip:

pip install azure-search-documents

Prasyarat

Untuk membuat layanan pencarian baru, Anda dapat menggunakan portal Azure, Azure PowerShell, atau Azure CLI.

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

Lihat memilih tingkat harga untuk informasi selengkapnya tentang opsi yang tersedia.

Mengautentikasi klien

Untuk berinteraksi dengan layanan Pencarian, Anda harus membuat instans kelas klien yang sesuai: SearchClient untuk mencari dokumen terindeks, SearchIndexClient untuk mengelola indeks, atau SearchIndexerClient untuk merayapi sumber data dan memuat dokumen pencarian ke dalam indeks. Untuk membuat instans objek klien, Anda memerlukan titik akhir dan kunci API. Anda dapat merujuk ke dokumentasi untuk informasi selengkapnya tentang pendekatan autentikasi yang didukung dengan layanan Pencarian.

Mendapatkan Kunci API

Anda bisa mendapatkan titik akhir dan kunci API dari layanan Pencarian di Portal Microsoft Azure. Silakan lihat dokumentasi untuk petunjuk tentang cara mendapatkan kunci API.

Atau, Anda dapat menggunakan perintah Azure CLI berikut untuk mengambil kunci API dari layanan Pencarian:

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

Ada dua jenis kunci yang digunakan untuk mengakses layanan pencarian Anda: kunci admin(baca-tulis) dan kueri(baca-saja). Membatasi akses dan operasi di aplikasi klien sangat penting untuk melindungi aset pencarian pada layanan Anda. Selalu gunakan kunci kueri, ketimbang kunci admin, untuk setiap kueri yang berasal dari aplikasi klien.

Catatan: Contoh cuplikan Azure CLI di atas mengambil kunci admin sehingga lebih mudah untuk mulai menjelajahi API, tetapi harus dikelola dengan hati-hati.

Membuat SearchClient

Untuk membuat SearchClientinstans , Anda memerlukan titik akhir, kunci API , dan nama indeks:

from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient

service_endpoint = os.environ["AZURE_SEARCH_SERVICE_ENDPOINT"]
index_name = os.environ["AZURE_SEARCH_INDEX_NAME"]
key = os.environ["AZURE_SEARCH_API_KEY"]

search_client = SearchClient(service_endpoint, index_name, AzureKeyCredential(key))

Membuat klien menggunakan autentikasi Azure Active Directory

Anda juga dapat membuat SearchClient, SearchIndexClient, atau SearchIndexerClient menggunakan autentikasi Azure Active Directory (AAD). Pengguna atau perwakilan layanan Anda harus diberi peran "Pembaca Data Indeks Pencarian". Menggunakan DefaultAzureCredential , Anda dapat mengautentikasi layanan menggunakan Identitas Terkelola atau perwakilan layanan, mengautentikasi sebagai pengembang yang bekerja pada aplikasi, dan banyak lagi tanpa mengubah kode. Silakan lihat dokumentasi untuk instruksi tentang cara menyambungkan ke Azure Cognitive Search menggunakan kontrol akses berbasis peran Azure (Azure RBAC).

Sebelum Anda dapat menggunakan DefaultAzureCredential, atau jenis kredensial apa pun dari Azure.Identity, Anda harus menginstal paket Azure.Identity terlebih dahulu.

Untuk menggunakan DefaultAzureCredential dengan ID klien dan rahasia, Anda harus mengatur AZURE_TENANT_IDvariabel lingkungan , , AZURE_CLIENT_IDdan AZURE_CLIENT_SECRET ; atau, Anda dapat meneruskan nilai tersebut ClientSecretCredential ke juga di Azure.Identity.

Pastikan Anda menggunakan namespace yang tepat untuk DefaultAzureCredential di bagian atas file sumber Anda:

from azure.identity import DefaultAzureCredential
from azure.search.documents import SearchClient

service_endpoint = os.getenv("AZURE_SEARCH_SERVICE_ENDPOINT")
index_name = os.getenv("AZURE_SEARCH_INDEX_NAME")
credential = DefaultAzureCredential()

search_client = SearchClient(service_endpoint, index_name, credential)

Konsep utama

Layanan Azure Cognitive Search berisi satu atau beberapa indeks yang menyediakan penyimpanan persisten data yang dapat dicari dalam bentuk dokumen JSON. (Jika Anda baru dalam pencarian, Anda dapat membuat analogi yang sangat kasar antara indeks dan tabel database.) Pustaka klien Azure.Search.Documents mengekspos operasi pada sumber daya ini melalui dua jenis klien utama.

Azure Cognitive Search menyediakan dua fitur canggih: Pencarian Semantik dan Pencarian Vektor.

Pencarian Semantik meningkatkan kualitas hasil pencarian untuk kueri berbasis teks. Dengan mengaktifkan Pencarian Semantik di layanan pencarian, Anda dapat meningkatkan relevansi hasil pencarian dengan dua cara:

  • Ini menerapkan peringkat sekunder ke kumpulan hasil awal, mempromosikan hasil yang paling relevan secara semantik ke bagian atas.
  • Ini mengekstrak dan mengembalikan keterangan dan jawaban dalam respons, yang dapat ditampilkan di halaman pencarian untuk meningkatkan pengalaman pencarian pengguna.

Untuk mempelajari selengkapnya tentang Pencarian Semantik, Anda dapat merujuk ke dokumentasi.

Pencarian Vektor adalah teknik pengambilan informasi yang mengatasi keterbatasan pencarian berbasis kata kunci tradisional. Alih-alih hanya mengandalkan analisis leksikal dan mencocokkan istilah kueri individual, Pencarian Vektor menggunakan model pembelajaran mesin untuk menangkap arti kontekstual kata dan frasa. Ini mewakili dokumen dan kueri sebagai vektor dalam ruang dimensi tinggi yang disebut penyematan. Dengan memahami niat di balik kueri, Pencarian Vektor dapat memberikan hasil yang lebih relevan yang selaras dengan persyaratan pengguna, bahkan jika istilah yang tepat tidak ada dalam dokumen. Selain itu, Pencarian Vektor dapat diterapkan ke berbagai jenis konten, termasuk gambar dan video, bukan hanya teks.

Untuk mempelajari cara mengindeks bidang vektor dan melakukan pencarian vektor, Anda dapat merujuk ke sampel. Sampel ini memberikan panduan terperinci tentang bidang vektor pengindeksan dan menunjukkan cara melakukan pencarian vektor.

Selain itu, untuk informasi yang lebih komprehensif tentang Pencarian Vektor, termasuk konsep dan penggunaannya, Anda dapat merujuk ke dokumentasi. Dokumentasi ini memberikan penjelasan dan panduan mendalam tentang memanfaatkan kekuatan Pencarian Vektor di Azure Cognitive Search.

Azure.Search.Documents Pustaka klien (v1) adalah penawaran baru untuk pengembang Python yang ingin menggunakan teknologi pencarian dalam aplikasi mereka. Ada pustaka klien yang lebih lama dan berfungsi Microsoft.Azure.Search penuh (v10) dengan banyak API yang terlihat serupa, jadi berhati-hatilah untuk menghindari kebingungan saat menjelajahi sumber daya online.

Contoh

Contoh berikut semuanya menggunakan himpunan data Hotel sederhana yang dapat Anda impor ke indeks Anda sendiri dari portal Azure. Ini hanya beberapa dasar - silakan lihat Sampel kami untuk lebih banyak lagi.

Melakukan Permintaan

Mari kita mulai dengan mengimpor namespace layanan kita.

import os
from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient

Kami kemudian akan membuat SearchClient untuk mengakses indeks pencarian hotel kami.

index_name = "hotels"
# Get the service endpoint and API key from the environment
endpoint = os.environ["SEARCH_ENDPOINT"]
key = os.environ["SEARCH_API_KEY"]

# Create a client
credential = AzureKeyCredential(key)
client = SearchClient(endpoint=endpoint,
                      index_name=index_name,
                      credential=credential)

Mari kita cari hotel "mewah".

results = client.search(search_text="luxury")

for result in results:
    print("{}: {})".format(result["hotelId"], result["hotelName"]))

Membuat indeks

Anda dapat menggunakan SearchIndexClient untuk membuat indeks pencarian. Bidang dapat didefinisikan menggunakan model , , SearchableFieldatau ComplexField yang nyamanSimpleField. Indeks juga dapat menentukan pemberi saran, penganalisis leksikal, dan banyak lagi.

client = SearchIndexClient(service_endpoint, AzureKeyCredential(key))
name = "hotels"
fields = [
    SimpleField(name="hotelId", type=SearchFieldDataType.String, key=True),
    SimpleField(name="baseRate", type=SearchFieldDataType.Double),
    SearchableField(name="description", type=SearchFieldDataType.String, collection=True),
    ComplexField(
        name="address",
        fields=[
            SimpleField(name="streetAddress", type=SearchFieldDataType.String),
            SimpleField(name="city", type=SearchFieldDataType.String),
        ],
        collection=True,
    ),
]
cors_options = CorsOptions(allowed_origins=["*"], max_age_in_seconds=60)
scoring_profiles: List[ScoringProfile] = []
index = SearchIndex(name=name, fields=fields, scoring_profiles=scoring_profiles, cors_options=cors_options)

result = client.create_index(index)

Menambahkan dokumen ke indeks Anda

Anda dapat Upload, Merge, MergeOrUpload, dan Delete beberapa dokumen dari indeks dalam satu permintaan batch. Ada beberapa aturan khusus untuk penggabungan yang harus diperhatikan.

DOCUMENT = {
    "category": "Hotel",
    "hotelId": "1000",
    "rating": 4.0,
    "rooms": [],
    "hotelName": "Azure Inn",
}

result = search_client.upload_documents(documents=[DOCUMENT])

print("Upload of new document succeeded: {}".format(result[0].succeeded))

Mengautentikasi di Cloud Nasional

Untuk mengautentikasi di National Cloud, Anda harus membuat tambahan berikut ke konfigurasi klien Anda:

  • Atur AuthorityHost dalam opsi kredensial atau melalui AZURE_AUTHORITY_HOST variabel lingkungan
  • Atur audience di SearchClient, SearchIndexClient, atau SearchIndexerClient
# Create a SearchClient that will authenticate through AAD in the China national cloud.
import os
from azure.identity import DefaultAzureCredential, AzureAuthorityHosts
from azure.search.documents import SearchClient

index_name = "hotels"
endpoint = os.environ["SEARCH_ENDPOINT"]
key = os.environ["SEARCH_API_KEY"]
credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_CHINA)

search_client = SearchClient(endpoint, index_name, credential=credential, audience="https://search.azure.cn")

Mengambil dokumen tertentu dari indeks Anda

Selain mengkueri dokumen menggunakan kata kunci dan filter opsional, Anda bisa mengambil dokumen tertentu dari indeks jika Anda sudah mengetahui kuncinya. Anda bisa mendapatkan kunci dari kueri, misalnya, dan ingin menampilkan informasi selengkapnya tentangnya atau menavigasi pelanggan Anda ke dokumen tersebut.

from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient

search_client = SearchClient(service_endpoint, index_name, AzureKeyCredential(key))

result = search_client.get_document(key="23")

print("Details for hotel '23' are:")
print("        Name: {}".format(result["hotelName"]))
print("      Rating: {}".format(result["rating"]))
print("    Category: {}".format(result["category"]))

API asinkron

Pustaka ini mencakup API asinkron lengkap. Untuk menggunakannya, Anda harus menginstal transportasi asinkron terlebih dahulu, seperti aiohttp. Lihat dokumentasi azure-core untuk informasi selengkapnya.

from azure.core.credentials import AzureKeyCredential
from azure.search.documents.aio import SearchClient

search_client = SearchClient(service_endpoint, index_name, AzureKeyCredential(key))

async with search_client:
    results = await search_client.search(search_text="spa")

    print("Hotels containing 'spa' in the name (or other fields):")
    async for result in results:
        print("    Name: {} (rating {})".format(result["hotelName"], result["rating"]))

Pemecahan Masalah

Umum

Klien Azure Cognitive Search akan memunculkan pengecualian yang ditentukan dalam Azure Core.

Pembuatan Log

Pustaka ini menggunakan pustaka pengelogan standar untuk pengelogan. Informasi dasar tentang sesi HTTP (URL, header, dll.) dicatat di tingkat INFO.

Pengelogan tingkat DEBUG mendetail, termasuk isi permintaan/respons dan header yang tidak diedit, dapat diaktifkan pada klien dengan argumen kata kunci logging_enable:

import sys
import logging
from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
client = SearchClient("<service endpoint>", "<index_name>", AzureKeyCredential("<api key>"), logging_enable=True)

Demikian pula, logging_enable dapat mengaktifkan pengelogan mendetail untuk satu operasi, meskipun tidak diaktifkan untuk klien:

result =  client.search(search_text="spa", logging_enable=True)

Langkah berikutnya

Berkontribusi

Lihat CONTRIBUTING.md Pencarian kami untuk detail tentang membangun, menguji, dan berkontribusi pada pustaka ini.

Proyek ini menyambut baik kontribusi dan saran. Sebagian besar kontribusi mengharuskan Anda menyetujui Perjanjian Lisensi Kontributor (CLA) yang menyatakan bahwa Anda memiliki hak untuk, dan benar-benar melakukannya, memberi kami hak untuk menggunakan kontribusi Anda. Untuk detailnya, kunjungi cla.microsoft.com.

Proyek ini telah mengadopsi Kode Etik Sumber Terbuka Microsoft. Untuk informasi selengkapnya, lihat Tanya Jawab Umum Tata Tertib atau hubungi opencode@microsoft.com untuk pertanyaan atau komentar lainnya.

Tayangan

Tayangan