Skip to content

azure-ai-integration.md

Latest commit

 

History

History
195 lines (143 loc) · 8.38 KB

azure-ai-integration.md

File metadata and controls

195 lines (143 loc) · 8.38 KB

Azure AI Integration

The repository includes functions specifically designed for Azure AI, supporting both Azure OpenAI models and general Azure AI services.

🔗 Learn More About Azure AI

Pipeline

Features

  • Azure OpenAI API Support
    Access models like GPT-4o, o3, and other fine-tuned AI models via Azure.

  • Azure AI Model Deployment
    Connect to custom models hosted on Azure AI.

  • Secure API Requests
    Supports API key authentication and environment variable configurations.

Environment Variables

Configure the following environment variables to enable Azure AI support:

# Custom prefix for pipeline display name (default: "Azure AI")
# The colon ":" will be added automatically between prefix and model name
# Examples: "Azure AI" → "Azure AI: gpt-4o", "My Azure" → "My Azure: gpt-4o"
AZURE_AI_PIPELINE_PREFIX="Azure AI"

# API key or token for Azure AI
AZURE_AI_API_KEY="your-api-key"

# Azure AI endpoint
# Examples:
# - For general Azure AI: "https://<your-endpoint>/chat/completions?api-version=2024-05-01-preview"
# - For Azure OpenAI: "https://<your-endpoint>/openai/deployments/<model-name>/chat/completions?api-version=2024-08-01-preview"
AZURE_AI_ENDPOINT="https://<your project>.services.ai.azure.com/models/chat/completions?api-version=2024-05-01-preview"

# Optional: model names (if not embedded in the URL)
# Supports semicolon or comma separated values: "gpt-4o;gpt-4o-mini" or "gpt-4o,gpt-4o-mini"
AZURE_AI_MODEL="gpt-4o;gpt-4o-mini"

# If true, the model name will be included in the request body
AZURE_AI_MODEL_IN_BODY=true

# Whether to use a predefined list of Azure AI models
USE_PREDEFINED_AZURE_AI_MODELS=false

# If true, use "Authorization: Bearer" instead of "api-key" header
AZURE_AI_USE_AUTHORIZATION_HEADER=false

# Azure AI Search endpoint for document retrieval (Only for Azure OpenAI)
# IMPORTANT: Azure AI Search only works with Azure OpenAI endpoints in this format:
# https://<deployment>.openai.azure.com/openai/deployments/<model>/chat/completions?api-version=2025-01-01-preview
AZURE_AI_ENDPOINT="https://<deployment>.openai.azure.com/openai/deployments/<model>/chat/completions?api-version=2025-01-01-preview"

# Azure AI Data Sources / RAG Configuration
# Complete JSON configuration for Azure Search - copy exactly and replace placeholder values
AZURE_AI_DATA_SOURCES='[{"type":"azure_search","parameters":{"endpoint":"https://<your-search-service>.search.windows.net","index_name":"<your-index-name>","authentication":{"type":"api_key","key":"<your-search-api-key>"}}}]'

# Enable relevance score extraction from Azure Search (default: true)
# When enabled, automatically adds include_contexts to get original_search_score and rerank_score
AZURE_AI_INCLUDE_SEARCH_SCORES=true

Azure AI Search / RAG Integration

The pipeline supports Azure AI Search integration for Retrieval-Augmented Generation (RAG). When configured, the pipeline automatically includes a data_sources field in requests to Azure AI, enabling document-based AI responses that can cite and reference your indexed content.

Important

Azure AI Search integration only works with Azure OpenAI endpoints in this specific format: https://<deployment>.openai.azure.com/openai/deployments/<model>/chat/completions?api-version=2025-01-01-preview

📖 Official Documentation

For detailed information about Azure AI Search configuration, please refer to:

⚙️ Configuration

Configure Azure AI Search by setting the AZURE_AI_DATA_SOURCES environment variable with your Azure Search configuration.

Simple Example:

AZURE_AI_DATA_SOURCES='[{"type":"azure_search","parameters":{"endpoint":"https://my-search.search.windows.net","index_name":"my-index","authentication":{"type":"api_key","key":"your-search-api-key"}}}]'

Tip

Copy the JSON exactly as shown above - this is the complete configuration that goes into the AZURE_AI_DATA_SOURCES field. Just replace:

  • my-search with your Azure Search service name
  • my-index with your search index name
  • your-search-api-key with your actual Azure Search API key

📋 Complete Configuration Template

[
  {
    "type": "azure_search",
    "parameters": {
      "endpoint": "https://YOUR-SEARCH-SERVICE.search.windows.net",
      "index_name": "YOUR-INDEX-NAME",
      "authentication": {
        "type": "api_key",
        "key": "YOUR-SEARCH-API-KEY"
      }
    }
  }
]

🔧 Advanced Configuration Options

For advanced use cases, you can include additional parameters:

[
  {
    "type": "azure_search",
    "parameters": {
      "endpoint": "https://YOUR-SEARCH-SERVICE.search.windows.net",
      "index_name": "YOUR-INDEX-NAME",
      "authentication": {
        "type": "api_key",
        "key": "YOUR-SEARCH-API-KEY"
      },
      "query_type": "vectorSimpleHybrid",
      "semantic_configuration": "default",
      "top_n_documents": 20,
      "strictness": 3,
      "role_information": "You are an AI assistant that helps with questions based on the provided documents."
    }
  }
]

🚀 Quick Setup Steps

  1. Create Azure Search Service - Set up an Azure Search service in the Azure portal
  2. Create and populate index - Upload your documents to a search index
  3. Get API key - Copy the API key from your Azure Search service
  4. Configure pipeline - Add the AZURE_AI_DATA_SOURCES environment variable
  5. Use Azure OpenAI endpoint - Ensure you're using the correct Azure OpenAI URL format

⚠️ Common Issues

  • Wrong endpoint format: Make sure you're using Azure OpenAI URLs, not regular Azure AI endpoints
  • Invalid JSON: Copy the JSON template exactly and only change the placeholder values
  • Missing API key: Ensure your Azure Search API key has proper permissions
  • Index not found: Verify your index name matches exactly (case-sensitive)

Native OpenWebUI Citation Support

The pipeline automatically provides native OpenWebUI citation support for Azure AI Search responses. When Azure AI Search is configured, the pipeline:

  1. Emits citation events via __event_emitter__ for the OpenWebUI frontend to display interactive citation cards
  2. Converts [docX] references to clickable markdown links that link directly to document URLs
  3. Extracts relevance scores when AZURE_AI_INCLUDE_SEARCH_SCORES=true
  4. Filters citations to only show documents actually referenced in the response

Example: Clickable Document Links

# Original Azure AI response
**Docker container actions** are a type of GitHub Actions [doc1]...

# Enhanced response (with clickable links)
**Docker container actions** are a type of GitHub Actions [[doc1]](https://example.com/README.md)...

Citation Card Features:

  • Source information with [docX] prefix for easy identification
  • Relevance percentage displayed on citation cards (requires AZURE_AI_INCLUDE_SEARCH_SCORES=true)
  • Document preview with content snippets
  • Clickable links to source documents when URLs are available
  • Streaming support with links converted inline as content streams

Relevance Score Selection:

The pipeline uses the filter_reason field from Azure Search to select the appropriate score:

  • filter_reason="rerank" → uses rerank_score
  • filter_reason="score" or not present → uses original_search_score

For more details, see the Azure AI Citations Documentation.

Tip

To use Azure OpenAI and other Azure AI models simultaneously, you can use the following URL: https://<your project>.services.ai.azure.com/models/chat/completions?api-version=2024-05-01-preview