name: rag-patterns description: Implement RAG (Retrieval-Augmented Generation) patterns using Azure AI Search. Covers three retrieval approaches - (1) Agentic Retrieval for complex multi-query LLM-assisted search with knowledge bases, (2) Full-Text Search using BM25 keyword matching, and (3) Vector Search for semantic similarity. Use when building RAG pipelines, implementing search for agents/chatbots, or grounding LLM responses in enterprise data. Supports hybrid search, semantic ranking, and azd templates for deployment.

RAG Patterns with Azure AI Search

Implement retrieval-augmented generation using Azure AI Search with three distinct patterns.

Quick Start

Installation

pip install azure-search-documents azure-identity
# For agentic retrieval (preview):
pip install azure-search-documents --pre

Authentication

from azure.identity import DefaultAzureCredential

# Keyless authentication (recommended)
credential = DefaultAzureCredential()

# Requires: az login
# Roles needed: Search Service Contributor, Search Index Data Contributor

Environment Variables

SEARCH_ENDPOINT=https://<service>.search.windows.net
SEARCH_INDEX_NAME=my-index
# For agentic retrieval:
AOAI_ENDPOINT=https://<resource>.openai.azure.com

RAG Pattern Selection Guide

Pattern	Use Case	Complexity	LLM Required
Full-Text Search	Keyword matching, exact terms	Low	No
Vector Search	Semantic similarity, meaning-based	Medium	Embedding model
Agentic Retrieval	Complex queries, multi-source, agents	High	Planning + synthesis

Decision Flow

Simple keyword search? → Full-Text Search
Need semantic understanding? → Vector Search or Hybrid
Complex multi-part queries for agents? → Agentic Retrieval
Best of both? → Hybrid (Full-Text + Vector)

Pattern 1: Full-Text Search

Traditional BM25 keyword-based search. Best for exact term matching.

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

client = SearchClient(
    endpoint="https://<service>.search.windows.net",
    index_name="hotels",
    credential=DefaultAzureCredential()
)

# Basic search
results = client.search(
    search_text="luxury hotel with pool",
    select=["HotelName", "Description", "Rating"],
    top=5
)

for result in results:
    print(f"{result['HotelName']}: {result['Rating']}")

Full-Text with Filters

results = client.search(
    search_text="hotel",
    filter="Rating gt 4 and ParkingIncluded eq true",
    order_by=["Rating desc"],
    facets=["Category"],
    select=["HotelName", "Rating", "Category"]
)

See: scripts/full_text_search.py for complete example.

Pattern 2: Vector Search

Semantic similarity search using embeddings. Finds conceptually related content.

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

client = SearchClient(
    endpoint="https://<service>.search.windows.net",
    index_name="hotels-vector",
    credential=DefaultAzureCredential()
)

# Vector query (embeddings pre-computed)
vector_query = VectorizedQuery(
    vector=query_embedding,  # 1536-dim float array
    k_nearest_neighbors=5,
    fields="DescriptionVector"
)

results = client.search(
    vector_queries=[vector_query],
    select=["HotelName", "Description"]
)

Hybrid Search (Full-Text + Vector)

# Combine keyword and vector search
results = client.search(
    search_text="historic hotel near restaurants",
    vector_queries=[vector_query],
    select=["HotelName", "Description"],
    top=5
)

Semantic Hybrid (with Reranking)

results = client.search(
    search_text="historic hotel near restaurants",
    vector_queries=[vector_query],
    query_type="semantic",
    semantic_configuration_name="my-semantic-config",
    top=5
)

See: scripts/vector_search.py for complete example.

Pattern 3: Agentic Retrieval

Multi-query pipeline for complex agent workflows. Decomposes queries, retrieves in parallel, synthesizes answers.

Key Concepts

Knowledge Base: Orchestrates retrieval across sources with LLM planning
Knowledge Source: Pointer to a search index with field mappings
Answer Synthesis: LLM-generated responses with citations

from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
    KnowledgeBase, KnowledgeSourceReference,
    KnowledgeBaseAzureOpenAIModel, AzureOpenAIVectorizerParameters,
    KnowledgeRetrievalOutputMode, SearchIndexKnowledgeSource,
    SearchIndexKnowledgeSourceParameters, SearchIndexFieldReference
)
from azure.search.documents.knowledgebases import KnowledgeBaseRetrievalClient
from azure.search.documents.knowledgebases.models import (
    KnowledgeBaseRetrievalRequest, KnowledgeBaseMessage,
    KnowledgeBaseMessageTextContent, SearchIndexKnowledgeSourceParams,
    KnowledgeRetrievalLowReasoningEffort
)
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
search_endpoint = "https://<service>.search.windows.net"
aoai_endpoint = "https://<resource>.openai.azure.com"

# Create knowledge source
index_client = SearchIndexClient(endpoint=search_endpoint, credential=credential)

ks = SearchIndexKnowledgeSource(
    name="my-knowledge-source",
    description="Product documentation",
    search_index_parameters=SearchIndexKnowledgeSourceParameters(
        search_index_name="products",
        source_data_fields=[
            SearchIndexFieldReference(name="id"),
            SearchIndexFieldReference(name="title")
        ]
    )
)
index_client.create_or_update_knowledge_source(knowledge_source=ks)

# Create knowledge base with LLM
aoai_params = AzureOpenAIVectorizerParameters(
    resource_url=aoai_endpoint,
    deployment_name="gpt-4o",
    model_name="gpt-4o"
)

kb = KnowledgeBase(
    name="my-knowledge-base",
    models=[KnowledgeBaseAzureOpenAIModel(azure_open_ai_parameters=aoai_params)],
    knowledge_sources=[KnowledgeSourceReference(name="my-knowledge-source")],
    output_mode=KnowledgeRetrievalOutputMode.ANSWER_SYNTHESIS,
    answer_instructions="Provide concise answers with citations."
)
index_client.create_or_update_knowledge_base(kb)

# Query the knowledge base
agent_client = KnowledgeBaseRetrievalClient(
    endpoint=search_endpoint,
    knowledge_base_name="my-knowledge-base",
    credential=credential
)

messages = [
    {"role": "user", "content": "What are the pricing tiers and features?"}
]

request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role=m["role"],
            content=[KnowledgeBaseMessageTextContent(text=m["content"])]
        ) for m in messages
    ],
    knowledge_source_params=[
        SearchIndexKnowledgeSourceParams(
            knowledge_source_name="my-knowledge-source",
            include_references=True,
            include_reference_source_data=True
        )
    ],
    include_activity=True,
    retrieval_reasoning_effort=KnowledgeRetrievalLowReasoningEffort
)

result = agent_client.retrieve(retrieval_request=request)

# Process response
for resp in result.response:
    for content in resp.content:
        print(content.text)

# Access citations
for ref in result.references:
    print(f"Source: {ref.doc_key}")

See: scripts/agentic_retrieval.py for complete example.

Creating Search Indexes

Full-Text Index

from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
    SearchIndex, SearchField, SearchableField, SimpleField
)

index = SearchIndex(
    name="hotels",
    fields=[
        SimpleField(name="id", type="Edm.String", key=True),
        SearchableField(name="HotelName", type="Edm.String", sortable=True),
        SearchableField(name="Description", type="Edm.String"),
        SimpleField(name="Rating", type="Edm.Double", filterable=True, sortable=True),
        SimpleField(name="Category", type="Edm.String", filterable=True, facetable=True)
    ]
)

index_client = SearchIndexClient(endpoint=endpoint, credential=credential)
index_client.create_or_update_index(index)

Vector Index

from azure.search.documents.indexes.models import (
    SearchIndex, SearchField, VectorSearch, VectorSearchProfile,
    HnswAlgorithmConfiguration, AzureOpenAIVectorizer,
    AzureOpenAIVectorizerParameters, SemanticSearch,
    SemanticConfiguration, SemanticPrioritizedFields, SemanticField
)

index = SearchIndex(
    name="hotels-vector",
    fields=[
        SimpleField(name="id", type="Edm.String", key=True),
        SearchableField(name="HotelName", type="Edm.String"),
        SearchableField(name="Description", type="Edm.String"),
        SearchField(
            name="DescriptionVector",
            type="Collection(Edm.Single)",
            searchable=True,
            vector_search_dimensions=1536,
            vector_search_profile_name="my-vector-profile"
        )
    ],
    vector_search=VectorSearch(
        profiles=[
            VectorSearchProfile(
                name="my-vector-profile",
                algorithm_configuration_name="my-hnsw",
                vectorizer_name="my-vectorizer"
            )
        ],
        algorithms=[HnswAlgorithmConfiguration(name="my-hnsw")],
        vectorizers=[
            AzureOpenAIVectorizer(
                vectorizer_name="my-vectorizer",
                parameters=AzureOpenAIVectorizerParameters(
                    resource_url=aoai_endpoint,
                    deployment_name="text-embedding-3-large",
                    model_name="text-embedding-3-large"
                )
            )
        ]
    ),
    semantic_search=SemanticSearch(
        configurations=[
            SemanticConfiguration(
                name="my-semantic-config",
                prioritized_fields=SemanticPrioritizedFields(
                    content_fields=[SemanticField(field_name="Description")]
                )
            )
        ]
    )
)

See: references/index-schemas.md for more schema patterns.

Deployment with azd

Use Azure Developer CLI templates for infrastructure deployment.

Initialize Project

# Clone a RAG template
azd init --template azure-search-openai-demo

# Or start fresh
azd init

Deploy Infrastructure

# Login and set subscription
azd auth login
az account set --subscription <subscription-id>

# Provision resources
azd provision

# Deploy application
azd deploy

Environment Configuration

# View deployed endpoints
azd env get-values

# Common outputs:
# AZURE_SEARCH_ENDPOINT
# AZURE_OPENAI_ENDPOINT
# AZURE_STORAGE_ACCOUNT

See: references/azd-templates.md for recommended templates.

Best Practices

Index Design

Include all searchable fields as SearchableField
Use SimpleField for filter/sort-only fields
Set appropriate analyzers for multilingual content
Include semantic configuration for ranking

Query Optimization

Use select to limit returned fields
Apply filters before text/vector search
Use top to limit results
Enable semantic ranking for relevance

Agentic Retrieval

Use KnowledgeRetrievalLowReasoningEffort for faster responses
Include source_data_fields for meaningful citations
Set clear answer_instructions for consistent output
Monitor activity logs for query decomposition insight

Security

Use DefaultAzureCredential for keyless auth
Assign minimum required roles
Enable Private Link for production
Implement document-level security filters

References

references/index-schemas.md - Index schema patterns
references/query-patterns.md - Query examples
references/azd-templates.md - Deployment templates
references/troubleshooting.md - Common issues

Example Scripts

scripts/full_text_search.py - Full-text search patterns
scripts/vector_search.py - Vector and hybrid search
scripts/agentic_retrieval.py - Agentic retrieval pipeline
scripts/create_index.py - Index creation examples

rag-patterns

SKILL.md