Cognitive Search でセマンティック キャプションに対するクエリを作成するCreate a query for semantic captions in Cognitive Search


セマンティック検索はパブリック プレビュー段階にあり、プレビューの REST API と Azure portal を介して利用できます。Semantic search is in public preview, available through the preview REST API and Azure portal. プレビュー機能は、補足利用規約に基づいて、現状のまま提供されます。Preview features are offered as-is, under Supplemental Terms of Use. これらの機能は課金対象です。These features are billable. 詳細については、可用性と価格に関するページを参照してください。For more information, see Availability and pricing.

この記事では、セマンティック ランク付けを使用して、関連する用語と語句を強調したセマンティック キャプション (および必要に応じてセマンティック回答) を返す検索要求を作成する方法について説明します。In this article, learn how to formulate a search request that uses semantic ranking and returns semantic captions (and optionally semantic answers), with highlights over the most relevant terms and phrases. "セマンティック" クエリの種類を使用して作成されたクエリでは、キャプションと回答の両方が返されます。Both captions and answers are returned in queries formulated using the "semantic" query type.

キャプションと回答は、検索ドキュメント内のテキストから逐語的に抽出されます。Captions and answers are extracted verbatim from text in the search document. セマンティック サブシステムでは、コンテンツのどの部分がキャプションまたは回答の特性を持つかは特定されますが、新しい文や語句は作成されません。The semantic subsystem determines what part of your content has the characteristics of a caption or answer, but it does not compose new sentences or phrases. このため、セマンティック検索には、説明または定義を含むコンテンツが最も適しています。For this reason, content that includes explanations or definitions work best for semantic search.


  • 米国中北部、米国西部、米国西部 2、米国東部 2、北ヨーロッパ、西ヨーロッパのいずれかのリージョンにある、Standard レベル (S1、S2、S3) の検索サービス。A search service at a Standard tier (S1, S2, S3), located in one of these regions: North Central US, West US, West US 2, East US 2, North Europe, West Europe. これらのリージョンのいずれかに既存の S1 以上のサービスがある場合は、新しいサービスを作成しなくてもアクセスを要求できます。If you have an existing S1 or greater service in one of these regions, you can request access without having to create a new service.

  • セマンティック検索プレビューへのアクセス: サインアップAccess to semantic search preview: sign up

  • 英語のコンテンツを含む既存の検索インデックスAn existing search index containing English content

  • クエリを送信するための検索クライアントA search client for sending queries

    検索クライアントは、クエリ要求でプレビューの REST API をサポートする必要があります。The search client must support preview REST APIs on the query request. PostmanVisual Studio Code、またはプレビューの API への REST 呼び出しを行うコードを使用できます。You can use Postman, Visual Studio Code, or code that makes REST calls to the preview APIs. Azure portal で Search エクスプローラーを使用してセマンティック クエリを送信することもできます。You can also use Search explorer in Azure portal to submit a semantic query.

  • クエリ要求には、この記事で説明するセマンティック オプションやその他のパラメーターを含める必要があります。A query request must include the semantic option and other parameters described in this article.

セマンティック クエリとはWhat's a semantic query?

Cognitive Search では、クエリは、クエリ処理と応答の形を決定するパラメーター化された要求です。In Cognitive Search, a query is a parameterized request that determines query processing and the shape of the response. "セマンティック クエリ" では、一致する結果のコンテキストと意味を評価し、関連性の高い一致を最上位に昇格させ、セマンティック回答とキャプションを返すことができるセマンティック再ランク付けモデルを呼び出すパラメーターが追加されます。A semantic query adds parameters that invoke the semantic reranking model that can assess the context and meaning of matching results, promote more relevant matches to the top, and return semantic answers and captions.

次の要求は、最小限のセマンティック クエリ (回答なし) を表しています。The following request is representative of a minimal semantic query (without answers).

POST https://[service name][index name]/docs/search?api-version=2020-06-30-Preview      
    "search": " Where was Alan Turing born?",    
    "queryType": "semantic",  
    "searchFields": "title,url,body",  
    "queryLanguage": "en-us"  

Cognitive Search のすべてのクエリと同様に、要求は、単一インデックスのドキュメント コレクションを対象とします。As with all queries in Cognitive Search, the request targets the documents collection of a single index. さらに、セマンティック クエリによって実行される分析、スキャン、およびスコアリングのシーケンスは、非セマンティック クエリと同じです。Furthermore, a semantic query undergoes the same sequence of parsing, analysis, scanning, and scoring as a non-semantic query.

違いは、関連性とスコアリングにあります。The difference lies in relevance and scoring. このプレビュー リリースで定義されているように、セマンティック クエリとは、その "結果" がセマンティック言語モデルを使用して再ランク付けされるものであり、既定の類似性ランク付けアルゴリズムによって割り当てられるスコアではなく、セマンティック ランカーによって最も関連性があると見なされる一致を明らかにする方法がとられます。As defined in this preview release, a semantic query is one whose results are reranked using a semantic language model, providing a way to surface the matches deemed most relevant by the semantic ranker, rather than the scores assigned by the default similarity ranking algorithm.

最初の結果の上位 50 件の一致のみを意味的にランク付けすることができます。すべての結果には応答にキャプションが含まれます。Only the top 50 matches from the initial results can be semantically ranked, and all include captions in the response. 必要に応じて、要求に answer パラメーターを指定して、可能性のある回答を抽出できます。Optionally, you can specify an answer parameter on the request to extract a potential answer. 詳細については、セマンティック回答に関するページを参照してください。For more information, see Semantic answers.

検索エクスプローラーを使用したクエリ実行Query with Search explorer

検索エクスプローラーは更新され、セマンティック クエリ用のオプションが含められました。Search explorer has been updated to include options for semantic queries. これらのオプションは、次の手順を完了した後にポータルに表示されます。These options become visible in the portal after completing the following steps:

  1. サインアップして、お使いの検索サービスがプレビュー プログラムに参加する許可を得ますSign up and admittance of your search service into the preview program

  2. 構文 を使用してポータルを開きますOpen the portal with this syntax:

クエリ オプションには、セマンティック クエリ、searchFields、およびスペル修正を有効にするスイッチが含まれています。Query options include switches to enable semantic queries, searchFields, and spell correction. 必要なクエリ パラメーターをクエリ文字列に貼り付けることもできます。You can also paste the required query parameters into the query string.

検索エクスプローラー内のクエリ オプション

REST を使用してクエリを実行するQuery using REST

ドキュメントの検索 (REST プレビュー) を使用して、プログラムで要求を作成します。Use the Search Documents (REST preview) to formulate the request programmatically.

応答には、キャプションと強調表示が自動的に含められます。A response includes captions and highlighting automatically. スペル修正または回答を応答に含める場合は、省略可能なパラメーターである speller または answers を要求に追加します。If you want the response to include spelling correction or answers, add an optional speller or answers parameter on the request.

次の例では、hotels-sample-index を使用して、セマンティック回答およびキャプションを含むセマンティック クエリ要求を作成します。The following example uses the hotels-sample-index to create a semantic query request with semantic answers and captions:

POST https://[service name]      
    "search": "newer hotel near the water with a great restaurant",
    "queryType": "semantic",
    "queryLanguage": "en-us",
    "searchFields": "HotelName,Category,Description",
    "speller": "lexicon",
    "answers": "extractive|count-3",
    "highlightPreTag": "<strong>",
    "highlightPostTag": "</strong>",
    "select": "HotelId,HotelName,Description,Category",
    "count": true

次の表は、セマンティック クエリで使用されるクエリ パラメーターを全体的に参照できるようにまとめたものです。The following table summarizes the query parameters used in a semantic query so that you can see them holistically. すべてのパラメーターの一覧については、「Search Documents (REST プレビュー)」を参照してくださいFor a list of all parameters, see Search Documents (REST preview)

パラメーターParameter TypeType 説明Description
queryTypequeryType StringString 有効な値は、simple、full、semantic です。Valid values include simple, full, and semantic. セマンティック クエリには、"semantic" の値が必要です。A value of "semantic" is required for semantic queries.
queryLanguagequeryLanguage StringString セマンティック クエリに必要です。Required for semantic queries. 現在、"en-us" のみが実装されています。Currently, only "en-us" is implemented.
searchFieldssearchFields StringString 検索可能なフィールドのコンマ区切りの一覧。A comma-delimited list of searchable fields. セマンティック ランク付けを行うフィールドを指定します。ここから、キャプションと回答が抽出されます。Specifies the fields over which semantic ranking occurs, from which captions and answers are extracted.

単純および完全なクエリの種類とは対照的に、フィールドの順番によって優先順位が決まります。In contrast with simple and full query types, the order in which fields are listed determines precedence. 使用方法の詳細については、「手順 2: searchFields を設定する」を参照してください。For more usage instructions, see Step 2: Set searchFields.
スペル チェックspeller StringString 検索エンジンに到達する前にスペルミスを修正する省略可能なパラメーターであり、セマンティック クエリに固有のものではない。Optional parameter, not specific to semantic queries, that corrects misspelled terms before they reach the search engine. 詳細については、クエリへのスペル修正の追加に関するページを参照してください。For more information, see Add spell correction to queries.
answersanswers StringString セマンティック回答を結果に含めるかどうかを指定する省略可能なパラメーター。Optional parameters that specify whether semantic answers are included in the result. 現在、"extractive" のみが実装されています。Currently, only "extractive" is implemented. 回答は、最大 5 つを返すように構成できます。Answers can be configured to return a maximum of five. 既定値は 1 です。The default is one. この例は、回答の数が 3 であることを示しています: "extractive|count3"。This example shows a count of three answers: "extractive|count3"`. 詳細については、セマンティック回答を返すに関するページを参照してください。For more information, see Return semantic answers.

要求を作成するFormulate the request

このセクションでは、セマンティック検索に必要なクエリ パラメーターについて、順を追って説明します。This section steps through the query parameters necessary for semantic search.

Step 1: queryType と queryLanguage を設定するStep 1: Set queryType and queryLanguage

REST に次のパラメーターを追加します。Add the following parameters to the rest. どちらのパラメーターも必須です。Both parameters are required.

"queryType": "semantic",
"queryLanguage": "en-us",

queryLanguage は、インデックス スキーマのフィールド定義に割り当てられている言語アナライザーと一致している必要があります。The queryLanguage must be consistent with any language analyzers assigned to field definitions in the index schema. queryLanguage が "en-us" の場合、言語アナライザーも英語のバリアント ("" または "en.lucene") である必要があります。If queryLanguage is "en-us", then any language analyzers must also be an English variant ("" or "en.lucene"). keyword や simple など、言語に依存しないアナライザーは、queryLanguage 値と競合しません。Any language-agnostic analyzers, such as keyword or simple, have no conflict with queryLanguage values.

クエリ要求でスペル修正も使用している場合、設定した queryLanguage は、speller、answers、および captions に等しく適用されます。In a query request, if you are also using spelling correction, the queryLanguage you set applies equally to speller, answers, and captions. 個々のパーツに対するオーバーライドはありません。There is no override for individual parts.

検索インデックスのコンテンツは複数の言語で構成できますが、通常、クエリ入力は 1 つの言語で行われます。While content in a search index can be composed in multiple languages, the query input is most likely in one. 検索エンジンでは、queryLanguage、言語アナライザー、およびコンテンツが構成されている言語の互換性が確認されません。そのため、誤った結果が生成されないように、適切にクエリのスコープを設定してください。The search engine doesn't check for compatibility of queryLanguage, language analyzer, and the language in which content is composed, so be sure to scope queries accordingly to avoid producing incorrect results.

手順 2: searchFields を設定するStep 2: Set searchFields

searchFields パラメーターは、クエリに対する "セマンティックの類似性" について評価すべき一節を識別するために使用されます。The searchFields parameter is used to identify passages to be evaluated for "semantic similarity" to the query. プレビューでは、処理すべき最も重要なフィールドに関するヒントがモデルに必要なため、searchFields を空白のままにすることはお勧めしません。For the preview, we do not recommend leaving searchFields blank as the model requires a hint as to what fields are the most important to process.

searchFields の順序は重要です。The order of the searchFields is critical. 単純および完全な Lucene クエリの既存のコードで既に searchFields を使用している場合は、セマンティック クエリの種類に切り替えるときにこのパラメーターを見直してフィールドの順序を確認してください。If you already use searchFields in existing code for simple or full Lucene queries, revisit this parameter to check for field order when switching to a semantic query type.

2 つ以上の searchFields の場合:For two or more searchFields:

  • コレクションには、文字列フィールドと最上位の文字列フィールドのみを含めます。Include only string fields and top-level string fields in collections. 文字列以外のフィールドまたは下位のフィールドをコレクションに含めると、エラーは発生しませんが、セマンティック ランク付けでそれらのフィールドは使用されません。If you happen to include non-string fields or lower-level fields in a collection, there is no error, but those fields won't be used in semantic ranking.

  • 最初のフィールドは、常に簡潔 (タイトルや名前など) にする必要があります。25 単語未満であると理想的です。First field should always be concise (such as a title or name), ideally under 25 words.

  • インデックスにテキスト ( のようにマシンにフォーカスされている形式ではなく、 のように人間が読める形式) の URL フィールドがある場合は、これをリストの 2 番目に配置します (または、簡潔なタイトル フィールドがない場合は先頭)。If the index has a URL field that is textual (human readable such as, and not machine focused such as, place it second in the list (or first if there is no concise title field).

  • これらのフィールドの後に、セマンティック クエリの回答が見つかる可能性がある説明フィールドを配置します (ドキュメントの主な内容など)。Follow those fields by descriptive fields where the answer to semantic queries may be found, such as the main content of a document.

フィールドが 1 つしか指定されていない場合は、ドキュメントの主な内容など、セマンティック クエリに対する回答が見つかる可能性のある説明フィールドを使用します。If only one field specified, use a descriptive field where the answer to semantic queries may be found, such as the main content of a document.

手順 3: orderBy 句を削除するStep 3: Remove orderBy clauses

既存の要求に orderBy 句が存在する場合はすべて削除します。Remove any orderBy clauses, if they exist in an existing request. 結果の順序付けにはセマンティック スコアが使用されます。明示的な並べ替えロジックを含めると、HTTP 400 エラーが返されます。The semantic score is used to order results, and if you include explicit sort logic, an HTTP 400 error is returned.

手順 4: 回答を追加するStep 4: Add answers

回答を提供する追加の処理を含める場合は、必要に応じて "answers" を追加します。Optionally, add "answers" if you want to include additional processing that provides an answer. 回答 (およびキャプション) は、searchFields にリストされているフィールド内の節から抽出されます。Answers (and captions) are extracted from passages found in fields listed in searchFields. 応答で最適な回答を得るために、十分な内容を持つフィールドを searchFields に含めてください。Be sure to include content-rich fields in searchFields to get the best answers in a response. 詳細については、セマンティック回答を戻す方法に関するページを参照してください。For more information, see How to return semantic answers.

手順 5: その他のパラメーターを追加するStep 5: Add other parameters

要求で必要なその他のパラメーターを設定します。Set any other parameters that you want in the request. spellerselect、count などのパラメーターを使用すると、要求の品質と応答の読みやすさが向上します。Parameters such as speller, select, and count improve the quality of the request and readability of the response.

必要に応じて、キャプションに適用される強調表示のスタイルをカスタマイズできます。Optionally, you can customize the highlight style applied to captions. キャプションでは、ドキュメント内の重要な一説 (応答を要約する部分) に強調の書式設定が適用されます。Captions apply highlight formatting over key passages in the document that summarize the response. 既定では、 <em>です。The default is <em>. 書式設定の種類 (黄色の背景など) を指定する場合は、highlightPreTag と highlightPostTag を設定できます。If you want to specify the type of formatting (for example, yellow background), you can set the highlightPreTag and highlightPostTag.

応答を評価するEvaluate the response

すべてのクエリと同様に、応答は、取得可能としてマークされているすべてのフィールド、または select パラメーターに指定されているフィールドのみで構成されます。As with all queries, a response is composed of all fields marked as retrievable, or just those fields listed in the select parameter. これには、元の関連性スコアが含まれます。また、要求の作成方法に応じて、カウントまたはバッチ結果が含まれる場合もあります。It includes the original relevance score, and might also include a count, or batched results, depending on how you formulated the request.

セマンティック クエリでは、次の追加の要素が応答に含められます: 意味的にランク付けされた新しい関連性スコア、プレーン テキスト内の強調表示されたキャプション、および必要に応じて回答。In a semantic query, the response has additional elements: a new semantically ranked relevance score, captions in plain text and with highlights, and optionally an answer.

クライアント アプリでは、特定のフィールドの内容全体ではなく、キャプションを一致の説明として含めるように、検索ページを構成することができます。In a client app, you can structure the search page to include a caption as the description of the match, rather than the entire contents of a specific field. これは、検索結果ページにおいて個々のフィールドの密度が高すぎる場合に役立ちます。This is useful when individual fields are too dense for the search results page.

上記のクエリ例に対する応答では、最上位の選択として次の一致が返されます。The response for the above example query returns the following match as the top pick. キャプションについては、プレーンテキスト バージョンと強調表示されたバージョンが自動的に返されます。Captions are returned automatically, with plain text and highlighted versions. この例では回答が省略されています。この特定のクエリとコーパスに対してそれを特定できなかったためです。Answers are omitted from the example because one could not be determined for this particular query and corpus.

"@odata.count": 35,
"@search.answers": [],
"value": [
        "@search.score": 1.8810667,
        "@search.rerankerScore": 1.1446577133610845,
        "@search.captions": [
                "text": "Oceanside Resort. Luxury. New Luxury Hotel. Be the first to stay. Bay views from every room, location near the pier, rooftop pool, waterfront dining & more.",
                "highlights": "<strong>Oceanside Resort.</strong> Luxury. New Luxury Hotel. Be the first to stay.<strong> Bay</strong> views from every room, location near the pier, rooftop pool, waterfront dining & more."
        "HotelName": "Oceanside Resort",
        "Description": "New Luxury Hotel. Be the first to stay. Bay views from every room, location near the pier, rooftop pool, waterfront dining & more.",
        "Category": "Luxury"

次のステップNext steps

セマンティック ランク付けと応答は最初の結果セットを基に構築されていることを思い出してください。Recall that semantic ranking and responses are built over an initial result set. 最初の結果の品質を向上させるロジックは、セマンティック検索に引き継がれます。Any logic that improves the quality of the initial results will carry forward to semantic search. 次の手順として、最初の結果に寄与する機能を確認します。これには、文字列のトークン化の方法に影響を与えるアナライザー、結果を調整できるスコアリング プロファイル、および既定の関連性アルゴリズムが含まれます。As a next step, review the features that contribute to initial results, including analyzers that affect how strings are tokenized, scoring profiles that can tune results, and the default relevance algorithm.