Cosmos.RAG.Embedding 0.2.0

Cosmos RAG Embedding

Un paquete NuGet simple y eficiente para generar embeddings de texto utilizando diferentes proveedores como Azure OpenAI y Ollama local.

¿Qué es RAG?

RAG (Retrieval-Augmented Generation) es una técnica que combina la recuperación de información con la generación de texto. Permite a los modelos de IA acceder a información externa y actualizada para proporcionar respuestas más precisas y contextualmente relevantes.

El proceso típico de RAG incluye:

1. Indexación: Convertir documentos en embeddings y almacenarlos en una base de datos vectorial
2. Recuperación: Buscar información relevante usando similaridad vectorial
3. Generación: Usar la información recuperada como contexto para generar respuestas

¿Qué son los Embeddings?

Los embeddings son representaciones numéricas (vectores) de texto que capturan el significado semántico. Textos con significados similares tendrán embeddings cercanos en el espacio vectorial.

Características clave:

• Vectores de números flotantes (típicamente 768-1536 dimensiones)
• Permiten búsquedas por similaridad semántica
• Esenciales para implementaciones de RAG
• Flexibles para usar con cualquier base de datos vectorial

Arquitectura del Proyecto

Este paquete proporciona una abstracción simple sobre diferentes servicios de embedding:

Cosmos.Contabilidad.RAG.Embedding/
├── IEmbeddingService.cs           # Interfaz principal
├── EmbeddingFactory.cs            # Factory para crear servicios
├── OpenAI/
│   ├── OpenAIEmbeddingService.cs      # Implementación Azure OpenAI
│   └── OpenAIEmbeddingConfiguration.cs # Configuración
└── Ollama/
    └── OllamaEmbeddingService.cs       # Implementación Ollama local

Componentes principales:

• IEmbeddingService: Contrato con método EmbeddingText()
• EmbeddingFactory: Métodos estáticos para crear instancias
• Implementaciones específicas: Azure OpenAI y Ollama
• Tipos de retorno: ReadOnlyMemory<float> para máxima flexibilidad

Instalación

dotnet add package Cosmos.RAG.Embedding

O agregando la referencia al .csproj:

<PackageReference Include="Cosmos.RAG.Embedding" Version="0.1.0" />

Uso Básico

Ejemplo con Azure OpenAI

using Cosmos.Contabilidad.RAG.Embedding;
using Cosmos.Contabilidad.RAG.Embedding.OpenAI;

// Configurar el servicio de Azure OpenAI
var config = new OpenAIEmbeddingConfiguration(
    Endpoint: "https://tu-instancia.openai.azure.com/",
    ApiKey: "tu-api-key",
    EmbeddingModel: "text-embedding-ada-002"
);

// Crear el servicio usando el factory
IEmbeddingService embeddingService = EmbeddingFactory.CreateWithOpenAI(config);

// Generar embedding para un texto
string texto = "Este es un texto de ejemplo para generar embedding";
var embedding = await embeddingService.EmbeddingText(texto, CancellationToken.None);

// El embedding es un ReadOnlyMemory<float> que puedes usar como necesites
Console.WriteLine($"Embedding generado con {embedding.Length} dimensiones");

// Convertir a array si es necesario
float[] embeddingArray = embedding.ToArray();

// O acceder directamente al span
ReadOnlySpan<float> embeddingSpan = embedding.Span;

Ejemplo con Ollama Local

// Crear servicio con configuración por defecto (localhost:11434)
IEmbeddingService embeddingService = EmbeddingFactory.CreateWithLocal();

// O con configuración personalizada
IEmbeddingService customService = EmbeddingFactory.CreateWithLocal(
    url: "http://localhost:11434/", 
    model: "nomic-embed-text:v1.5"
);

// Generar embedding
var embedding = await embeddingService.EmbeddingText("Texto a embebir", CancellationToken.None);

Configuración

Azure OpenAI

• Endpoint: URL de tu instancia de Azure OpenAI
• ApiKey: Clave de API de Azure
• EmbeddingModel: Modelo a usar (ej: "text-embedding-ada-002")
• Dimensiones: Fijas en 768 dimensiones

Ollama Local

• URL: Por defecto "http://localhost:11434/"
• Modelo: Por defecto "nomic-embed-text:v1.5"
• Requisito: Ollama debe estar ejecutándose localmente

Integración con Bases de Datos Vectoriales

Los embeddings generados son compatibles con múltiples bases de datos:

PostgreSQL con pgvector

using Pgvector;

// Convertir ReadOnlyMemory<float> a Vector de pgvector
var embedding = await embeddingService.EmbeddingText("Mi texto");
var pgVector = new Vector(embedding.ToArray());

// Insertar en PostgreSQL
await connection.ExecuteAsync(
    "INSERT INTO documentos (texto, embedding) VALUES (@texto, @embedding)",
    new { texto = "Mi documento", embedding = pgVector }
);

Otros sistemas vectoriales

// Para sistemas que requieren float[]
float[] embeddingArray = embedding.ToArray();

// Para sistemas que trabajan con listas
List<float> embeddingList = embedding.ToArray().ToList();

// Para acceso directo sin copia (más eficiente)
ReadOnlySpan<float> embeddingSpan = embedding.Span;

Características

✅ Múltiples proveedores: Azure OpenAI y Ollama
✅ Async/await: Soporte completo para operaciones asíncronas
✅ Cancellation tokens: Para cancelar operaciones largas
✅ Tipo flexible: ReadOnlyMemory<float> para máxima compatibilidad
✅ Configuración tipada: Records inmutables para configuración
✅ Factory pattern: Creación simple de servicios
✅ Sin dependencias específicas: Compatible con cualquier BD vectorial

Requisitos

• .NET 9.0 o superior
• Para Azure OpenAI: Instancia de Azure OpenAI configurada
• Para Ollama: Ollama ejecutándose localmente con modelo de embedding

Licencia

Este proyecto está bajo la licencia de Cosmos.