Azure Rag Foundry Workshop

🤖 RAG Chat con Azure AI Foundry

Sistema de chat con Retrieval-Augmented Generation (RAG) usando Azure AI Foundry, Azure AI Search y Tool Calling.

📋 Descripción

Este proyecto implementa un sistema completo de Q&A sobre documentos PDF que incluye:

• Indexación de PDFs con extracción de texto e imágenes
• Búsqueda semántica con Azure AI Search (vectorial + híbrida)
• Tool Calling para que el modelo use herramientas automáticamente
• Procesamiento asíncrono con Azure Service Bus y Functions
• MCP Server para integración con VS Code Copilot

🏗️ Arquitectura

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Frontend      │────▶│   Web App        │────▶│  Azure OpenAI   │
│   (HTML/JS)     │     │   (FastAPI)      │     │  (GPT-4.1)      │
└─────────────────┘     └────────┬─────────┘     └─────────────────┘
                                 │
                    ┌────────────┼────────────┐
                    ▼            ▼            ▼
            ┌───────────┐ ┌───────────┐ ┌───────────────┐
            │ AI Search │ │  Service  │ │   Computer    │
            │ (Vectors) │ │   Bus     │ │    Vision     │
            └───────────┘ └─────┬─────┘ └───────────────┘
                                │
                                ▼
                        ┌───────────────┐
                        │ Azure Function│
                        │ (Queue Worker)│
                        └───────────────┘

📁 Estructura del Proyecto

proyecto-rag-azure/
├── webapp/                    # Aplicación web principal
│   ├── backend/
│   │   ├── app.py            # API FastAPI con RAG y Tool Calling
│   │   └── queue_processor.py # Procesador de cola (local)
│   ├── frontend/
│   │   ├── index.html        # Interfaz del chat
│   │   ├── app.js            # Lógica del frontend
│   │   └── styles.css        # Estilos
│   ├── requirements.txt      # Dependencias Python
│   ├── run.py                # Script para ejecutar localmente
│   └── startup.sh            # Script de inicio en Azure
│
├── functions/                 # Azure Function para procesar cola
│   ├── function_app.py       # Trigger de Service Bus
│   ├── host.json             # Configuración de Functions
│   └── requirements.txt      # Dependencias
│
├── mcp/                       # MCP Server para VS Code
│   ├── mcp_server.py         # Versión completa (offline)
│   └── mcp_server_lite.py    # Versión lite (usa API)
│
├── scripts/                   # Scripts auxiliares
│   ├── crear_indice_rag.py   # Crear índice en AI Search
│   ├── indexar_documentos.py # Indexar PDFs manualmente
│   ├── busqueda_rag.py       # Probar búsquedas
│   └── verificar_ambiente.py # Verificar configuración
│
├── .vscode/
│   └── mcp.json              # Configuración MCP para Copilot
│
├── .env                       # Variables de entorno
└── README.md                  # Este archivo

🚀 Requisitos Previos

Azure Resources

• Azure AI Foundry con modelos desplegados:

- gpt-4.1 (o similar) para chat - text-embedding-3-small para embeddings

• Azure AI Search (Basic o superior)
• Azure App Service (Linux, Python 3.11)
• Azure Service Bus (opcional, para cola)
• Azure Storage (opcional, para blobs)
• Azure Functions (opcional, para procesamiento async)

Local

• Python 3.11+
• Azure CLI (az login)
• VS Code con GitHub Copilot (opcional, para MCP)

⚙️ Configuración

1. Variables de Entorno

Crea un archivo .env en la raíz:

# Azure OpenAI / AI Foundry
AZURE_OPENAI_ENDPOINT=https://tu-recurso.cognitiveservices.azure.com/
AZURE_OPENAI_API_VERSION=2024-08-01-preview
AZURE_CHAT_MODEL=gpt-4.1
AZURE_EMBEDDING_MODEL=text-embedding-3-small

# Azure AI Search
AZURE_SEARCH_ENDPOINT=https://tu-search.search.windows.net
AZURE_SEARCH_KEY=tu-api-key
AZURE_SEARCH_INDEX=documentos-pdf-rag

# Azure Computer Vision (para imágenes en PDFs)
AZURE_VISION_ENDPOINT=https://tu-recurso.cognitiveservices.azure.com/

# Azure Service Bus (opcional)
AZURE_SERVICEBUS_NAMESPACE=tu-namespace.servicebus.windows.net
AZURE_SERVICEBUS_QUEUE=pdf-processing-queue

# Azure Storage (opcional)
AZURE_STORAGE_ACCOUNT=tu-storage
AZURE_STORAGE_CONTAINER=pdf-uploads

# Web App URL (para MCP lite)
AZURE_WEBAPP_URL=https://tu-webapp.azurewebsites.net

2. Instalar Dependencias

cd webapp
pip install -r requirements.txt

🖥️ Ejecución Local

Opción 1: Script de inicio

cd webapp
python run.py

Opción 2: Uvicorn directo

cd webapp/backend
uvicorn app:app --reload --port 8000

Abre http://localhost:8000 en tu navegador.

☁️ Despliegue en Azure

Web App

cd webapp
az webapp up --name tu-webapp --resource-group tu-rg --runtime "PYTHON:3.11"

Configurar Startup Command

az webapp config set --name tu-webapp --resource-group tu-rg \
  --startup-file "cd backend && gunicorn --bind=0.0.0.0:8000 --workers=2 --timeout=120 app:app -k uvicorn.workers.UvicornWorker"

Azure Function (para cola)

cd functions
func azure functionapp publish tu-function-app

🔧 Uso del MCP con VS Code

1. Configurar .vscode/mcp.json

{
  "servers": {
    "workshop-rag": {
      "type": "stdio",
      "command": "python",
      "args": ["${workspaceFolder}/mcp/mcp_server_lite.py"],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "MCP_API_BASE": "https://tu-webapp.azurewebsites.net"
      }
    }
  }
}

2. Recargar VS Code

Ctrl+Shift+P → "Developer: Reload Window"

3. Usar en Copilot Chat

Cambia a modo Agent y las herramientas estarán disponibles:

• buscar_documentos - Buscar en PDFs indexados
• chat - Hacer preguntas con RAG
• listar_documentos - Ver documentos disponibles
• estado_sistema - Verificar conexión

📖 Endpoints de la API

Ejemplo: Chat con RAG

curl -X POST https://tu-webapp.azurewebsites.net/api/chat \
  -H "Content-Type: application/json" \
  -d '{"mensaje": "¿Qué dice el documento sobre sostenibilidad?"}'

🛠️ Herramientas Disponibles (Tool Calling)

El modelo tiene acceso a estas herramientas:

📊 Recursos de Azure Creados

🔍 Troubleshooting

Error 429 (Rate Limit)

Aumenta la capacidad del modelo de embeddings:

az cognitiveservices account deployment create \
  --name tu-ai-services \
  --resource-group tu-rg \
  --deployment-name text-embedding-3-small \
  --model-name text-embedding-3-small \
  --model-version 1 \
  --model-format OpenAI \
  --sku-capacity 350 \
  --sku-name Standard

MCP no carga

1. Verifica que mcp_server_lite.py existe
2. Revisa que MCP_API_BASE apunta a la URL correcta
3. Recarga VS Code completamente

Documentos no aparecen

El endpoint /api/documentos consulta Azure AI Search. Verifica:

1. El índice existe: documentos-pdf-rag
2. Hay documentos indexados
3. La API key es correcta

📄 Licencia

MIT License - Libre para uso educativo y comercial.

👥 Autor

Creado durante el Azure AI Foundry Workshop.