AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

azure-search-documents-py

Azure AI Search SDK for Python. Use for vector search, hybrid search, semantic ranking, indexing, and skillsets. Triggers: "azure-search-documents", "SearchClient", "SearchIndexClient", "vector search", "hybrid search", "semantic search".

Original source
microsoft
License
MIT
Pinned revision
3f5b461b2314e01c400564051e92469114c5b68f

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read microsoft--azure-search-documents-py at revision 3f5b461b2314e01c400564051e92469114c5b68f, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 4

references/semantic-ranking.md

Semantic Ranking Patterns

Semantic ranking uses machine learning to re-rank search results for better relevance.

Semantic Configuration

Basic Semantic Configuration

from azure.search.documents.indexes.models import (
    SemanticSearch,
    SemanticConfiguration,
    SemanticPrioritizedFields,
    SemanticField,
)

semantic_search = SemanticSearch(
    default_configuration_name="my-semantic-config",
    configurations=[
        SemanticConfiguration(
            name="my-semantic-config",
            prioritized_fields=SemanticPrioritizedFields(
                title_field=SemanticField(field_name="title"),
                content_fields=[
                    SemanticField(field_name="content"),
                    SemanticField(field_name="summary")
                ],
                keywords_fields=[
                    SemanticField(field_name="tags")
                ]
            )
        )
    ]
)

Field Priority Rules

| Field Type | Max Fields | Purpose | |------------|------------|---------| | title_field | 1 | Most important for ranking | | content_fields | 10 | Main content, ordered by priority | | keywords_fields | 10 | Keywords/tags for matching |

Semantic Queries

Basic Semantic Query

from azure.search.documents.models import QueryType

def semantic_search(client, query: str):
    """Execute a semantic search query."""
    results = client.search(
        search_text=query,
        query_type=QueryType.SEMANTIC,
        semantic_configuration_name="my-semantic-config",
        select=["id", "title", "content"]
    )
    
    return list(results)

Semantic Search with Captions

Captions provide extractive summaries highlighting relevant passages.

from azure.search.documents.models import QueryType, QueryCaptionType

def semantic_search_with_captions(client, query: str):
    """Semantic search with extractive captions."""
    results = client.search(
        search_text=query,
        query_type=QueryType.SEMANTIC,
        semantic_configuration_name="my-semantic-config",
        query_caption=QueryCaptionType.EXTRACTIVE,
        select=["id", "title", "content"]
    )
    
    for result in results:
        print(f"Title: {result['title']}")
        print(f"Score: {result['@search.score']}")
        print(f"Reranker Score: {result.get('@search.reranker_score', 'N/A')}")
        
        # Extract captions
        captions = result.get("@search.captions", [])
        for caption in captions:
            print(f"Caption: {caption.text}")
            print(f"Highlights: {caption.highlights}")

Semantic Search with Answers

Answers extract specific text that directly answers the query.

from azure.search.documents.models import QueryType, QueryCaptionType, QueryAnswerType

def semantic_search_with_answers(client, query: str):
    """Semantic search with extractive answers."""
    results = client.search(
        search_text=query,
        query_type=QueryType.SEMANTIC,
        semantic_configuration_name="my-semantic-config",
        query_caption=QueryCaptionType.EXTRACTIVE,
        query_answer=QueryAnswerType.EXTRACTIVE,
        query_answer_count=3,  # Request up to 3 answers
        select=["id", "title", "content"]
    )
    
    # Get semantic answers (top-level, not per-document)
    answers = results.get_answers()
    if answers:
        for answer in answers:
            print(f"Answer: {answer.text}")
            print(f"Highlights: {answer.highlights}")
            print(f"Score: {answer.score}")
            print(f"Key: {answer.key}")
    
    # Process documents
    for result in results:
        print(f"Document: {result['title']}")

Hybrid Search with Semantic Ranking

Combine keyword, vector, and semantic ranking for best results.

from azure.search.documents.models import (
    VectorizedQuery,
    QueryType,
    QueryCaptionType,
)

def hybrid_semantic_search(
    client,
    query: str,
    query_vector: list[float],
    top: int = 10
):
    """Hybrid search with semantic re-ranking."""
    vector_query = VectorizedQuery(
        vector=query_vector,
        k_nearest_neighbors=50,  # Over-fetch for re-ranking
        fields="content_vector"
    )
    
    results = client.search(
        search_text=query,
        vector_queries=[vector_query],
        query_type=QueryType.SEMANTIC,
        semantic_configuration_name="my-semantic-config",
        query_caption=QueryCaptionType.EXTRACTIVE,
        top=top,
        select=["id", "title", "content"]
    )
    
    return list(results)

Semantic Configuration for Different Content Types

Document Search

doc_semantic_config = SemanticConfiguration(
    name="document-semantic-config",
    prioritized_fields=SemanticPrioritizedFields(
        title_field=SemanticField(field_name="document_title"),
        content_fields=[
            SemanticField(field_name="body_text"),
            SemanticField(field_name="abstract")
        ],
        keywords_fields=[
            SemanticField(field_name="categories"),
            SemanticField(field_name="authors")
        ]
    )
)

Product Search

product_semantic_config = SemanticConfiguration(
    name="product-semantic-config",
    prioritized_fields=SemanticPrioritizedFields(
        title_field=SemanticField(field_name="product_name"),
        content_fields=[
            SemanticField(field_name="description"),
            SemanticField(field_name="features")
        ],
        keywords_fields=[
            SemanticField(field_name="brand"),
            SemanticField(field_name="category")
        ]
    )
)

FAQ Search

faq_semantic_config = SemanticConfiguration(
    name="faq-semantic-config",
    prioritized_fields=SemanticPrioritizedFields(
        title_field=SemanticField(field_name="question"),
        content_fields=[
            SemanticField(field_name="answer")
        ],
        keywords_fields=[
            SemanticField(field_name="topic")
        ]
    )
)

Multiple Semantic Configurations

Define different configurations for different query patterns.

semantic_search = SemanticSearch(
    default_configuration_name="general-config",
    configurations=[
        SemanticConfiguration(
            name="general-config",
            prioritized_fields=SemanticPrioritizedFields(
                title_field=SemanticField(field_name="title"),
                content_fields=[SemanticField(field_name="content")]
            )
        ),
        SemanticConfiguration(
            name="qa-config",
            prioritized_fields=SemanticPrioritizedFields(
                title_field=SemanticField(field_name="question"),
                content_fields=[SemanticField(field_name="answer")]
            )
        )
    ]
)

# Use specific config at query time
results = client.search(
    search_text=query,
    query_type=QueryType.SEMANTIC,
    semantic_configuration_name="qa-config"  # Override default
)

Best Practices

  1. Title field: Always specify a title field for best ranking
  2. Content field order: List most important content fields first
  3. Over-fetch: Request more results than needed, let semantic re-ranking select the best
  4. Captions for UI: Use captions to show relevant snippets in search results
  5. Answers for Q&A: Use answers for question-answering scenarios
  6. Combine with hybrid: Semantic ranking works best with hybrid (keyword + vector) search