Python 用Azure Cognitive Search クライアント ライブラリ - バージョン 11.4.0

  • [アーティクル]

Azure Cognitive Search は、Web、モバイル、およびエンタープライズ アプリケーションのプライベートな異種コンテンツに対するリッチな検索機能を追加するための API とツールを開発者に提供する、サービスとしての検索クラウド ソリューションです。

Azure Cognitive Search サービスは、次のアプリケーション シナリオに適しています。

  • さまざまなコンテンツ タイプを 1 つの検索可能なインデックスに統合します。 インデックスを設定するには、コンテンツを含む JSON ドキュメントをプッシュするか、データが既に Azure にある場合は、データを自動的にプルするインデクサーを作成します。
  • スキルセットをインデクサーにアタッチして、画像や大きなテキスト ドキュメントから検索可能なコンテンツを作成します。 スキルセットは、組み込みの OCR、エンティティ認識、キー フレーズ抽出、言語検出、テキスト翻訳、感情分析に Cognitive Services の AI を活用します。 カスタム スキルを追加して、データ インジェスト中にコンテンツの外部処理を統合することもできます。
  • 検索クライアント アプリケーションで、商用 Web 検索エンジンと同様のクエリ ロジックとユーザー エクスペリエンスを実装します。

Azure.Search.Documents クライアント ライブラリを使用して、次の手順を実行します。

  • あいまい検索、ワイルドカード検索、正規表現を含むシンプルで高度なクエリ フォームのクエリを送信します。
  • ファセット ナビゲーション、地理空間検索、またはフィルター条件に基づいて結果を絞り込むためのフィルター処理されたクエリを実装します。
  • 検索インデックスを作成および管理します。
  • 検索インデックス内のドキュメントをアップロードして更新します。
  • Azure からインデックスにデータをプルするインデクサーを作成および管理します。
  • AI エンリッチメントをデータ インジェストに追加するスキルセットを作成および管理します。
  • 高度なテキスト分析または多言語コンテンツ用のアナライザーを作成および管理します。
  • スコアリング プロファイルを使用して結果を最適化し、ビジネス ロジックや鮮度を考慮します。

ソースコード | パッケージ (PyPI) | パッケージ (Conda) | API リファレンス ドキュメント | 製品ドキュメント | サンプル

作業の開始

パッケージをインストールする

pip を使用して Python 用Azure Cognitive Search クライアント ライブラリをインストールします。

pip install azure-search-documents

前提条件

新しい検索サービスを作成するには、Azure portal、Azure PowerShell、または Azure CLI を使用できます。

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

使用可能なオプションの詳細については、「 価格レベルの選択 」を参照してください。

クライアントを認証する

Search Serviceを操作するには、適切なクライアント クラスSearchClientのインスタンスを作成する必要があります。インデックス付きドキュメントの検索、インデックスの管理、SearchIndexClientデータ SearchIndexerClient ソースのクロール、インデックスへの検索ドキュメントの読み込みなどです。 クライアント オブジェクトをインスタンス化するには、 エンドポイント と API キーが必要です。 Search Serviceでサポートされている認証方法の詳細については、ドキュメントを参照してください。

API キーを取得する

エンドポイントと API キーは、Azure Portal のSearch Serviceから取得できます。 API キーを取得する方法については、 ドキュメント を参照してください。

または、次の Azure CLI コマンドを使用して、Search Serviceから API キーを取得することもできます。

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

検索サービスへのアクセスに使用されるキーには、admin(read-write) キーと query(読み取り専用) キーの 2 種類があります。 クライアント アプリでアクセスと操作を制限することは、サービスで検索アセットを保護するために不可欠です。 クライアント アプリから発信されたクエリには、常に管理者キーではなくクエリ キーを使用します。

注: 上記の Azure CLI スニペットの例では管理キーが取得されるため、API の探索を簡単に開始できますが、慎重に管理する必要があります。

SearchClient を作成する

を SearchClientインスタンス化するには、 エンドポイント、 API キー 、 インデックス名が必要です。

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))

Azure Active Directory 認証を使用してクライアントを作成する

、、または SearchIndexerClient Azure Active Directory (AAD) 認証を使用して作成SearchClientSearchIndexClientすることもできます。 ユーザーまたはサービス プリンシパルには、"検索インデックス データ閲覧者" ロールが割り当てられている必要があります。 DefaultAzureCredential を使用すると、マネージド ID またはサービス プリンシパルを使用してサービスを認証したり、アプリケーションに取り組んでいる開発者として認証したり、コードを変更せずに認証したりすることができます。 Azure ロールベースのアクセス制御 (Azure RBAC) を使用してAzure Cognitive Searchに接続する方法については、ドキュメントを参照してください。

または Azure.Identity から任意の資格情報のDefaultAzureCredential種類を使用する前に、まず Azure.Identity パッケージをインストールする必要があります。

クライアント ID とシークレットで を使用DefaultAzureCredentialするには、、AZURE_CLIENT_ID、および AZURE_CLIENT_SECRET 環境変数をAZURE_TENANT_ID設定する必要があります。または、これらの値を ClientSecretCredential Azure.Identity の にも渡すことができます。

ソース ファイルの先頭にある に適切な名前空間 DefaultAzureCredential を使用していることを確認します。

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)

主要な概念

Azure Cognitive Search サービスには、JSON ドキュメントの形式で検索可能なデータの永続的なストレージを提供する 1 つ以上のインデックスが含まれています。 (検索を初めて使用する場合は、インデックスとデータベース テーブルの間で非常に大まかな類似を行うことができます)。Azure.Search.Documents クライアント ライブラリは、2 種類のメインクライアントを通じて、これらのリソースに対する操作を公開します。

Azure Cognitive Searchには、セマンティック検索とベクター検索の 2 つの強力な機能が用意されています。

セマンティック検索 では、テキストベースのクエリの検索結果の品質が向上します。 検索サービスでセマンティック検索を有効にすると、次の 2 つの方法で検索結果の関連性を向上させることができます。

  • 最初の結果セットにセカンダリ ランク付けが適用され、最も意味的に関連性の高い結果が上位に昇格されます。
  • 応答でキャプションと回答を抽出して返します。これは、ユーザーの検索エクスペリエンスを向上させるために検索ページに表示できます。

セマンティック検索の詳細については、ドキュメントを参照 してください。

ベクター検索は、従来のキーワード (keyword)ベースの検索の制限を克服する情報取得手法です。 Vector Search では、字句分析のみに依存し、個々のクエリ用語を一致させる代わりに、機械学習モデルを利用して単語やフレーズのコンテキストの意味をキャプチャします。 これは、埋め込みと呼ばれる高次元空間内のベクトルとしてドキュメントとクエリを表します。 ベクター検索は、クエリの背後にある意図を理解することで、ドキュメントに正確な用語が存在しない場合でも、ユーザーの要件に合わせてより関連性の高い結果を提供できます。 さらに、ベクター検索は、テキストだけでなく、画像やビデオなど、さまざまな種類のコンテンツに適用できます。

ベクター フィールドにインデックスを付け、ベクター検索を実行する方法については、 サンプルを参照してください。 このサンプルでは、ベクター フィールドのインデックス作成に関する詳細なガイダンスを提供し、ベクター検索を実行する方法を示します。

さらに、ベクター検索の概念や使用方法など、ベクター検索に関するより包括的な情報については、ドキュメントを参照 してください。 このドキュメントでは、Azure Cognitive Searchでの Vector Search の機能の活用に関する詳細な説明とガイダンスを提供します。

Azure.Search.Documentsクライアント ライブラリ (v1) は、アプリケーションで検索テクノロジを使用する Python 開発者向けのまったく新しいオファリングです。 似たような API を多数備えた古い完全な機能 Microsoft.Azure.Search を備えたクライアント ライブラリ (v10) があるため、オンライン リソースを探索するときに混乱を避けるように注意してください。

例

次の例では、すべて、Azure portalから独自のインデックスにインポートできる単純な Hotel データ セットを使用しています。これらは基本のほんの一部です。詳細については、「サンプル」をチェックしてください。

クエリ実行

まず、名前空間をインポートします。

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

次に、 を SearchClient 作成してホテル検索インデックスにアクセスします。

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)

「高級」ホテルを検索しましょう。

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

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

インデックスの作成

を SearchIndexClient 使用して、検索インデックスを作成できます。 フィールドは、便利な SimpleField、、 SearchableFieldまたは ComplexField モデルを使用して定義できます。 インデックスでは、suggester、字句アナライザーなどを定義することもできます。

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)

インデックスへのドキュメントの追加

1 つのバッチ要求で、インデックスから、、、およびDelete複数のドキュメントを作成できます。UploadMergeMergeOrUpload 注意すべき マージには、いくつかの特別なルール があります。

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))

National Cloud での認証

National Cloud で認証するには、クライアント構成に次の追加を行う必要があります。

  • 資格情報オプションまたは環境変数を使用して を設定しますAZURE_AUTHORITY_HOST。AuthorityHost
  • 、、または で SearchIndexClientSearchClientを設定しますaudienceSearchIndexerClient
# 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")

インデックスから特定のドキュメントを取得する

キーワードとオプションのフィルターを使用してドキュメントのクエリを実行するだけでなく、キーがわかっている場合は、インデックスから特定のドキュメントを取得できます。 たとえば、クエリからキーを取得し、それに関する詳細情報を表示したり、顧客をそのドキュメントに移動したりできます。

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

このライブラリには、完全な非同期 API が含まれています。 これを使用するには、まず、 aiohttp などの非同期トランスポートをインストールする必要があります。 詳細については、 azure-core のドキュメント を参照してください。

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"]))

トラブルシューティング

全般

Azure Cognitive Search クライアントは、Azure Core で定義されている例外を発生させます。

ログの記録

このライブラリでは、ログ記録に標準 のログ ライブラリが使用されます。 HTTP セッションに関する基本情報 (URL、ヘッダーなど) は INFO レベルでログに記録されます。

要求/応答本文と編集されていないヘッダーを含む詳細なデバッグ レベルのログ記録は、次のように 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)

同様に、logging_enable は、詳細なログ記録がクライアントで有効になっていない場合でも、1 回の操作のために有効にすることができます。

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

次のステップ

共同作成

このライブラリの構築、テスト、および投稿の詳細については、 検索 CONTRIBUTING.md を参照してください。

このプロジェクトでは、共同作成と提案を歓迎しています。 ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。 詳細については、「 cla.microsoft.com」を参照してください。

このプロジェクトでは、Microsoft オープン ソースの倫理規定を採用しています。 詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。

インプレッション数

インプレッション数