> For the complete documentation index, see [llms.txt](https://public-intelligence.gitbook.io/taina-agente-ia-ogtic/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://public-intelligence.gitbook.io/taina-agente-ia-ogtic/referencias-tecnicas/integrations/google-gemini.md).

# Google Gemini

Esta guía explica cómo Taína utiliza Google Gemini como modelo de lenguaje principal para comprensión y generación de texto.

Google Gemini es el modelo de lenguaje grande (LLM) que permite a Taína:

* **Comprensión de Lenguaje**: Procesar consultas en español natural
* **Generación de Respuestas**: Crear respuestas contextualizadas
* **Embeddings**: Generar vectores para búsqueda semántica
* **RAG Integration**: Integración con sistema de recuperación aumentada

## Configuración de Google Gemini

### 1. Obtener API Key

#### Google AI Studio

```bash
# 1. Ir a Google AI Studio
# https://makersuite.google.com/app/apikey

# 2. Crear nueva API key
# 3. Copiar la clave generada

# 4. Configurar en .env
GOOGLE_API_KEY=your_google_api_key
```

#### Google Cloud Console (Alternativo)

```bash
# 1. Ir a Google Cloud Console
# https://console.cloud.google.com/

# 2. Habilitar Generative AI API
# 3. Crear credenciales de servicio
# 4. Descargar archivo JSON de credenciales
```

### 2. Configuración en Taína

```python
# src/llm/gemini_llm.py - Configuración del LLM
from langchain_google_genai import ChatGoogleGenerativeAI
from langchain_google_genai import GoogleGenerativeAIEmbeddings

# Configuración del LLM
llm = ChatGoogleGenerativeAI(
    model="gemini-1.5-flash",
    google_api_key=os.getenv("GOOGLE_API_KEY"),
    temperature=0.7,
    max_tokens=1000,
    convert_system_message_to_human=True
)

# Configuración de embeddings
embeddings = GoogleGenerativeAIEmbeddings(
    model="models/embedding-001",
    google_api_key=os.getenv("GOOGLE_API_KEY")
)
```

### 3. Variables de Entorno

```ini
# Google Gemini Configuration
GOOGLE_API_KEY=your_google_api_key

# Opcional: Configuración avanzada
GOOGLE_MODEL=gemini-1.5-flash
GOOGLE_TEMPERATURE=0.7
GOOGLE_MAX_TOKENS=1000
GOOGLE_EMBEDDING_MODEL=models/embedding-001
```

## Configuración del agente

### Prompt Engineering

```python
# src/prompts.py - Prompts optimizados para Gemini
AGENT_INSTRUCTIONS = """
Eres Taína, asistente virtual del Gobierno de la República Dominicana.

INSTRUCCIONES PRINCIPALES:
- Responde SIEMPRE en español dominicano
- Sé amable, profesional y servicial
- Proporciona información precisa sobre servicios gubernamentales
- Si no sabes algo, admítelo y ofrece alternativas
- Usa las herramientas disponibles para obtener información actualizada

CONTEXTO DEL SISTEMA:
- Tienes acceso a información de servicios gubernamentales dominicanos
- Puedes buscar servicios por nombre, institución o palabra clave
- Puedes obtener detalles específicos como costos, ubicaciones y requisitos
- Puedes acceder a canales digitales y información de contacto
"""

DATA_STRUCTURE_CONTEXT = """
ESTRUCTURA DE DATOS DISPONIBLES:
- Servicios principales con descripción general
- Variaciones de servicios con costos y requisitos específicos
- Ubicaciones de oficinas con direcciones y horarios
- Canales digitales con enlaces y procedimientos online
- Información de contacto con teléfonos y correos
- Pares pregunta-respuesta para consultas frecuentes
"""
```

### Configuración de herramientas

```python
# src/main.py - Configuración del agente con herramientas
class ProductionAssistant(Agent):
    def __init__(self) -> None:
        super().__init__(
            instructions=COMBINED_PROMPT,
            tools=[
                list_services,           # Buscar servicios
                get_service_overview,    # Información general
                list_service_variations, # Categorías y costos
                get_service_locations,   # Ubicaciones
                get_service_digital_channel, # Canales online
                get_service_contact,     # Información de contacto
                ask_knowledge_base,      # Búsqueda semántica
                get_current_date,        # Fecha actual
            ],
        )
```

## Embeddings y búsqueda semántica

### Configuración de embeddings

```python
# src/embeddings/gemini_embedding.py
from langchain_google_genai import GoogleGenerativeAIEmbeddings

def get_google_embeddings():
    """Obtiene el modelo de embeddings de Google Gemini"""
    return GoogleGenerativeAIEmbeddings(
        model="models/embedding-001",
        google_api_key=os.getenv("GOOGLE_API_KEY")
    )
```

### Búsqueda semántica

```python
# src/vectors/chroma_vector.py - Integración con ChromaDB
from langchain_core.vectorstores import VectorStoreRetriever

def get_chroma_load(embeddings, directory, collection_name, retriever_k=3):
    """Crea retriever de ChromaDB con embeddings de Gemini"""
    
    # Cargar base de datos vectorial
    vectorstore = Chroma(
        collection_name=collection_name,
        embedding_function=embeddings,
        persist_directory=directory
    )
    
    # Crear retriever
    retriever = VectorStoreRetriever(
        vectorstore=vectorstore,
        search_type="similarity",
        search_kwargs={"k": retriever_k}
    )
    
    return retriever
```

## Manejo de errores

### Errores comunes

#### Error: "API quota exceeded"

```python
# Implementar backoff exponencial
import time
import random

async def call_gemini_with_retry(prompt, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = await llm.ainvoke(prompt)
            return response
        except Exception as e:
            if "quota" in str(e).lower():
                delay = (2 ** attempt) + random.uniform(0, 1)
                print(f"Quota exceeded, waiting {delay:.2f}s...")
                time.sleep(delay)
            else:
                raise e
    raise Exception("Max retries exceeded")
```

#### Error: "Invalid API key"

```bash
# Verificar API key
python3 -c "
import os
from dotenv import load_dotenv
load_dotenv()

api_key = os.getenv('GOOGLE_API_KEY')
if api_key:
    print(f'API Key: {api_key[:10]}...')
    print('Length:', len(api_key))
else:
    print('API Key not found')
"
```

### Manejo de rate limits

```python
# src/utils/rate_limiter.py
import asyncio
from datetime import datetime, timedelta

class RateLimiter:
    def __init__(self, max_requests=100, time_window=60):
        self.max_requests = max_requests
        self.time_window = time_window
        self.requests = []
    
    async def acquire(self):
        now = datetime.now()
        # Limpiar requests antiguos
        self.requests = [req for req in self.requests 
                        if now - req < timedelta(seconds=self.time_window)]
        
        if len(self.requests) >= self.max_requests:
            sleep_time = self.time_window - (now - self.requests[0]).seconds
            await asyncio.sleep(sleep_time)
        
        self.requests.append(now)
```

## Optimización de rendimiento

### Configuración de modelo

```python
# Configuración optimizada para producción
llm_config = {
    "model": "gemini-1.5-flash",      # Modelo más rápido
    "temperature": 0.7,               # Balance creatividad/precisión
    "max_tokens": 1000,               # Límite de tokens
    "top_p": 0.9,                     # Nucleus sampling
    "top_k": 40,                      # Top-k sampling
    "frequency_penalty": 0.0,          # Penalización de frecuencia
    "presence_penalty": 0.0           # Penalización de presencia
}
```

### Caching de respuestas

```python
# src/utils/cache.py
import hashlib
import json
from functools import lru_cache

class ResponseCache:
    def __init__(self, max_size=1000):
        self.cache = {}
        self.max_size = max_size
    
    def get_cache_key(self, prompt, context):
        """Genera clave única para el cache"""
        content = f"{prompt}:{json.dumps(context, sort_keys=True)}"
        return hashlib.md5(content.encode()).hexdigest()
    
    def get(self, prompt, context):
        key = self.get_cache_key(prompt, context)
        return self.cache.get(key)
    
    def set(self, prompt, context, response):
        key = self.get_cache_key(prompt, context)
        if len(self.cache) >= self.max_size:
            # Eliminar entrada más antigua
            oldest_key = next(iter(self.cache))
            del self.cache[oldest_key]
        self.cache[key] = response
```

## Validación operativa

### Verificación de conectividad

```python
# verify_gemini_connection.py
import asyncio
from langchain_google_genai import ChatGoogleGenerativeAI

async def validate_gemini_connection():
    """Verifica conectividad básica con Gemini"""
    try:
        llm = ChatGoogleGenerativeAI(
            model="gemini-1.5-flash",
            google_api_key=os.getenv("GOOGLE_API_KEY")
        )
        
        response = await llm.ainvoke("Hola, ¿cómo estás?")
        print("✅ Gemini conectado exitosamente")
        print(f"Respuesta: {response.content}")
        
    except Exception as e:
        print(f"❌ Error conectando con Gemini: {e}")

asyncio.run(validate_gemini_connection())
```

### Verificación de embeddings

```python
# verify_embeddings.py
import asyncio
from src.embeddings.gemini_embedding import get_google_embeddings

async def validate_embeddings():
    """Confirma la generación de embeddings"""
    try:
        embeddings = get_google_embeddings()
        
        # Ejemplo con texto de referencia
        sample_text = "licencia de conducir"
        vector = await embeddings.aembed_query(sample_text)
        
        print("✅ Embeddings generados exitosamente")
        print(f"Dimensiones: {len(vector)}")
        print(f"Primeros 5 valores: {vector[:5]}")
        
    except Exception as e:
        print(f"❌ Error generando embeddings: {e}")

asyncio.run(validate_embeddings())
```

## Monitoreo y métricas

### Métricas de uso

```python
# src/utils/metrics.py
class GeminiMetrics:
    def __init__(self):
        self.request_count = 0
        self.total_tokens = 0
        self.error_count = 0
        self.response_times = []
    
    def record_request(self, tokens, response_time, error=False):
        self.request_count += 1
        self.total_tokens += tokens
        self.response_times.append(response_time)
        if error:
            self.error_count += 1
    
    def get_stats(self):
        return {
            "total_requests": self.request_count,
            "total_tokens": self.total_tokens,
            "error_rate": self.error_count / max(self.request_count, 1),
            "avg_response_time": sum(self.response_times) / len(self.response_times),
            "tokens_per_request": self.total_tokens / max(self.request_count, 1)
        }
```

### Health check

```python
# src/tools.py - Health check para Gemini
@function_tool()
async def health_check() -> str:
    """Verifica el estado del sistema incluyendo Gemini"""
    
    status = {
        "timestamp": datetime.now().isoformat(),
        "gemini": "unknown",
        "knowledge_base": "unknown",
        "memory_usage": "unknown"
    }
    
    # Verificar Gemini
    try:
        llm = ChatGoogleGenerativeAI(
            model="gemini-1.5-flash",
            google_api_key=os.getenv("GOOGLE_API_KEY")
        )
        response = await llm.ainvoke("test")
        status["gemini"] = "healthy"
    except Exception as e:
        status["gemini"] = f"error: {str(e)}"
    
    return json.dumps(status)
```

## Configuración avanzada

### Modelos disponibles

```python
# Modelos de Gemini disponibles
models = {
    "gemini-1.5-flash": {
        "description": "Modelo rápido y eficiente",
        "use_case": "Producción, respuestas rápidas",
        "max_tokens": 8192,
        "cost": "Bajo"
    },
    "gemini-1.5-pro": {
        "description": "Modelo más potente",
        "use_case": "Tareas complejas, análisis detallado",
        "max_tokens": 32768,
        "cost": "Alto"
    },
    "gemini-1.0-pro": {
        "description": "Modelo estable",
        "use_case": "Tareas generales",
        "max_tokens": 30720,
        "cost": "Medio"
    }
}
```

### Configuración de seguridad

```python
# Configuración de seguridad
security_config = {
    "content_filtering": True,      # Filtrado de contenido
    "safety_settings": {
        "harassment": "BLOCK_MEDIUM_AND_ABOVE",
        "hate_speech": "BLOCK_MEDIUM_AND_ABOVE",
        "dangerous_content": "BLOCK_MEDIUM_AND_ABOVE"
    },
    "data_retention": "30_days",    # Retención de datos
    "audit_logging": True          # Logging de auditoría
}
```

## Recursos adicionales

* [Google Gemini Documentation](https://ai.google.dev/docs)
* [LangChain Google Integration](https://python.langchain.com/docs/integrations/llms/google_vertex_ai)
* [Google AI Studio](https://makersuite.google.com/)
* [Gemini API Reference](https://ai.google.dev/docs/reference)

## Próximos pasos

1. **Integración Deepgram**: [Deepgram Integration](/taina-agente-ia-ogtic/referencias-tecnicas/integrations/deepgram.md)
2. **Integración ElevenLabs**: [ElevenLabs Integration](/taina-agente-ia-ogtic/referencias-tecnicas/integrations/elevenlabs.md)
3. **Arquitectura de la Base de Conocimientos**: [Arquitectura de la base de conocimiento](/taina-agente-ia-ogtic/arquitectura-y-conceptos/architecture/knowledge-base.md)
4. **Referencia de Configuración**: [Referencia de Configuración](/taina-agente-ia-ogtic/referencias-tecnicas/api/configuration.md)

***

¿Necesitas ayuda? Consulta la [guía de solución de problemas](https://github.com/public-intelligence/taina_ogtic/blob/master/taina-gitbook-ogtic/taina-asistente-ia/index/how-to/troubleshoot.md) o la [documentación de configuración](/taina-agente-ia-ogtic/referencias-tecnicas/api/configuration.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://public-intelligence.gitbook.io/taina-agente-ia-ogtic/referencias-tecnicas/integrations/google-gemini.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.