How to Intermediate · 4 min read

Semantic Kernel with Azure AI Search

Quick answer
Use semantic_kernel Python SDK to connect Semantic Kernel with Azure AI Search by configuring the Azure Cognitive Search endpoint and API key as a retriever. Then add this retriever to the kernel to enable AI-powered semantic search and chat completions. This integration leverages OpenAIChatCompletion for LLM calls and Azure Search for document retrieval.

PREREQUISITES

  • Python 3.8+
  • Azure Cognitive Search service with index and API key
  • Azure OpenAI or OpenAI API key
  • pip install semantic-kernel>=1.0 openai>=1.0

Setup

Install the required Python packages and set environment variables for Azure Cognitive Search and OpenAI API keys.

  • Install Semantic Kernel and OpenAI SDK: pip install semantic-kernel openai
  • Set environment variables:
    • AZURE_SEARCH_ENDPOINT: Your Azure Cognitive Search endpoint URL
    • AZURE_SEARCH_API_KEY: Your Azure Cognitive Search admin or query API key
    • OPENAI_API_KEY: Your OpenAI or Azure OpenAI API key
bash
pip install semantic-kernel openai

Step by step

This example shows how to create a Semantic Kernel instance, configure Azure AI Search as a retriever, and use OpenAI chat completions for semantic search and chat.

python
import os
import semantic_kernel as sk
from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion
from semantic_kernel.connectors.memory.azure_search import AzureCognitiveSearchMemory

# Initialize kernel
kernel = sk.Kernel()

# Add OpenAI chat completion service
kernel.add_service(OpenAIChatCompletion(
    service_id="chat",
    api_key=os.environ["OPENAI_API_KEY"],
    ai_model_id="gpt-4o-mini"
))

# Configure Azure Cognitive Search memory retriever
search_endpoint = os.environ["AZURE_SEARCH_ENDPOINT"]
search_api_key = os.environ["AZURE_SEARCH_API_KEY"]
search_index_name = "your-index-name"  # Replace with your Azure Search index name

azure_search_memory = AzureCognitiveSearchMemory(
    endpoint=search_endpoint,
    api_key=search_api_key,
    index_name=search_index_name
)

# Add the Azure Search memory to kernel
kernel.register_memory(azure_search_memory)

# Example: Add a document to Azure Search (optional, requires index setup)
# azure_search_memory.upload_documents([
#     {"id": "1", "content": "Azure AI Search enables semantic search capabilities."}
# ])

# Query the Azure Search memory
query = "What is Azure AI Search?"
results = azure_search_memory.search(query, top_k=3)

print("Search results:")
for doc in results:
    print(f"- {doc['content']}")

# Use kernel chat service to generate a completion based on retrieved docs
context = "\n".join(doc["content"] for doc in results)
prompt = f"Answer the question based on the following context:\n{context}\nQuestion: {query}"

response = kernel.run("chat", prompt)
print("\nChat completion:")
print(response)
output
Search results:
- Azure AI Search enables semantic search capabilities.
- ... (other relevant documents)

Chat completion:
Azure AI Search is a cloud service that provides powerful semantic search capabilities, enabling you to find relevant information quickly using AI-powered natural language understanding.

Common variations

  • Use async methods with Semantic Kernel for asynchronous calls.
  • Switch to different OpenAI models by changing ai_model_id (e.g., gpt-4o or gpt-4o-mini).
  • Use Azure OpenAI deployment names instead of OpenAI model names if using Azure OpenAI service.
  • Customize Azure Search queries with filters or semantic configurations via AzureCognitiveSearchMemory parameters.
python
import asyncio

async def async_search_and_chat():
    kernel = sk.Kernel()
    kernel.add_service(OpenAIChatCompletion(
        service_id="chat",
        api_key=os.environ["OPENAI_API_KEY"],
        ai_model_id="gpt-4o-mini"
    ))
    azure_search_memory = AzureCognitiveSearchMemory(
        endpoint=os.environ["AZURE_SEARCH_ENDPOINT"],
        api_key=os.environ["AZURE_SEARCH_API_KEY"],
        index_name="your-index-name"
    )
    kernel.register_memory(azure_search_memory)

    query = "Explain semantic search"
    results = await azure_search_memory.search_async(query, top_k=3)

    context = "\n".join(doc["content"] for doc in results)
    prompt = f"Based on the context:\n{context}\nExplain semantic search."

    response = await kernel.run_async("chat", prompt)
    print(response)

# asyncio.run(async_search_and_chat())

Troubleshooting

  • If you get authentication errors, verify your AZURE_SEARCH_API_KEY and OPENAI_API_KEY environment variables are set correctly.
  • If no search results appear, confirm your Azure Cognitive Search index exists and contains documents.
  • For model errors, ensure the ai_model_id matches a valid OpenAI or Azure OpenAI deployment.
  • Check network connectivity to Azure endpoints and OpenAI API.

Key Takeaways

  • Use Semantic Kernel's AzureCognitiveSearchMemory to integrate Azure AI Search as a retriever.
  • Add OpenAIChatCompletion service to Semantic Kernel for LLM-powered chat completions.
  • Set environment variables for Azure Search endpoint, API key, and OpenAI API key securely.
  • You can run synchronous or asynchronous queries with Semantic Kernel and Azure AI Search.
  • Troubleshoot by verifying keys, index existence, and model deployment names.
Verified 2026-04 · gpt-4o-mini
Verify ↗