{"id":29182565,"url":"https://github.com/yosoykevin/rag-caching-techniques","last_synced_at":"2026-05-01T08:31:18.199Z","repository":{"id":301868485,"uuid":"1010527207","full_name":"YoSoyKevin/rag-caching-techniques","owner":"YoSoyKevin","description":"API RAG con FastAPI y pgvector, implementando Exact y Semantic Cache con embeddings de Google Gemini.","archived":false,"fork":false,"pushed_at":"2025-06-29T09:15:26.000Z","size":15,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-29T10:24:32.981Z","etag":null,"topics":["fastapi","llm","pgvector","postgresql","python","rag"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/YoSoyKevin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-29T09:05:51.000Z","updated_at":"2025-06-29T09:17:28.000Z","dependencies_parsed_at":"2025-06-29T10:34:40.173Z","dependency_job_id":null,"html_url":"https://github.com/YoSoyKevin/rag-caching-techniques","commit_stats":null,"previous_names":["yosoykevin/rag-caching-techniques"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/YoSoyKevin/rag-caching-techniques","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YoSoyKevin%2Frag-caching-techniques","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YoSoyKevin%2Frag-caching-techniques/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YoSoyKevin%2Frag-caching-techniques/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YoSoyKevin%2Frag-caching-techniques/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/YoSoyKevin","download_url":"https://codeload.github.com/YoSoyKevin/rag-caching-techniques/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YoSoyKevin%2Frag-caching-techniques/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263029214,"owners_count":23402354,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastapi","llm","pgvector","postgresql","python","rag"],"created_at":"2025-07-01T20:06:42.373Z","updated_at":"2026-05-01T08:31:18.193Z","avatar_url":"https://github.com/YoSoyKevin.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LangChain RAG API con FastAPI, PostgreSQL (pgvector) y Google Gemini\n\n## Enfoque: Semantic Cache y Exact Cache\n\nEste proyecto está enfocado en la implementación y demostración de dos técnicas clave para optimizar sistemas RAG (Retrieval-Augmented Generation):\n\n### ¿Qué es Exact Cache?\n- **Exact Cache** almacena y reutiliza respuestas para prompts que coinciden exactamente con consultas previas.\n- Es ideal para reducir latencia y costo cuando los usuarios repiten preguntas idénticas.\n- En este proyecto, el endpoint `/rag/query_exact` implementa esta técnica.\n\n### ¿Qué es Semantic Cache?\n- **Semantic Cache** almacena respuestas y las recupera cuando una nueva consulta es semánticamente similar (aunque no idéntica) a una consulta previa.\n- Utiliza embeddings y búsqueda de similitud para encontrar coincidencias.\n- El endpoint `/rag/query_semantic` implementa esta técnica.\n\n### ¿Por qué son importantes?\n- **Ahorro de costos:** Menos llamadas al LLM.\n- **Reducción de latencia:** Respuestas inmediatas desde cache.\n- **Mejor experiencia de usuario:** Respuestas coherentes y rápidas.\n- **Escalabilidad:** Menor carga en el backend y el modelo.\n\n---\n\n## Ejemplo de uso\n\n### Exact Cache\n```bash\ncurl -X POST http://localhost:8000/rag/query_exact \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"prompt\": \"¿Cuál es la capital de Francia?\"}'\n```\n\n### Semantic Cache\n```bash\ncurl -X POST http://localhost:8000/rag/query_semantic \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"prompt\": \"¿Qué ciudad es la capital de Francia?\"}'\n```\n\n---\n\nEste proyecto es una base profesional para sistemas de Retrieval Augmented Generation (RAG) usando LangChain (\u003e=0.2.x), FastAPI y PostgreSQL con la extensión pgvector. Incluye integración con Google Gemini para embeddings y LLM, y está listo para producción pequeña o media.\n\n## Estructura de Carpetas\n\n```\n├── src\n│   ├── app\n│   │   ├── db           # Lógica de conexión y utilidades de base de datos\n│   │   ├── schemas      # Modelos Pydantic (requests/responses)\n│   │   ├── middleware   # Middlewares (logging, etc)\n│   │   └── dependencies # Inyección de dependencias\n│   ├── cache            # Lógica de cache (exacto y semántico)\n│   ├── indexer          # Lógica de indexado y almacenamiento de embeddings\n│   └── retriever        # Lógica de recuperación RAG\n├── config               # Configuración y variables de entorno\n├── db                   # Scripts SQL para la base de datos\n├── docs                 # Documentación adicional (tipos de cache, etc)\n├── tests                # Pruebas automáticas con pytest\n├── README.md            # Documentación\n├── requirements.txt     # Dependencias\n├── Dockerfile           # Imagen de la app FastAPI\n└── docker-compose.yml   # Orquestación de contenedores\n```\n\n## Características\n- RAG con LangChain (LCEL)\n- Embeddings y LLM: Google Gemini API\n- Vector store: PostgreSQL + pgvector\n- API REST para consulta y reindexado\n- Logging y caché de prompts\n- Pruebas automáticas con pytest\n- Listo para producción pequeña/mediana\n\n## Requisitos\n- Python \u003e= 3.10\n- Docker y docker-compose\n- Clave API de Google Gemini (variable de entorno `GOOGLE_API_KEY`)\n- (Opcional) Umbral de cache semántico: `CACHE_DISTANCE_THRESHOLD` (por defecto: -0.95). Para similitud coseno, valores más cercanos a -1 son más similares. Ajusta este valor en tu `.env` para controlar la sensibilidad del semantic cache. Ahora solo se considera hit si la distancia del embedding más cercano está entre -1 y el threshold configurado.\n- En los logs del semantic cache se muestra el porcentaje de similitud aproximado: -1.0 equivale a 100% similar, 0.0 a 50%, y 1.0 a 0%. El sistema considera hit si la distancia es menor o igual al threshold configurado (más negativa = más similar).\n\n## Despliegue rápido\n\n1. Copia tu clave de Google Gemini en `config/.env`:\n   ```\n   GOOGLE_API_KEY=tu_clave\n   POSTGRES_USER=postgres\n   POSTGRES_PASSWORD=postgres\n   POSTGRES_DB=postgres\n   POSTGRES_HOST=localhost\n   POSTGRES_PORT=5432\n   EMBEDDING_MODEL=models/embedding-001  # Modelo de embeddings de Google Gemini\n   LLM_MODEL=gemini-2.5-flash           # Modelo LLM de Google Gemini\n   CACHE_DISTANCE_THRESHOLD=-0.95\n   ```\n2. Instala las dependencias y levanta el servidor:\n   ```bash\n   pip install -r requirements.txt\n   uvicorn src.app.main:app --reload\n   ```\n   \n### Despliegue con Docker\n\n1. Asegúrate de tener tu archivo `.env` en la carpeta `config/` con las variables necesarias.\n2. Levanta todo el stack (API + base de datos) con:\n\n   ```bash\n   docker-compose up --build\n   ```\n\n3. La API estará disponible en [http://localhost:8000](http://localhost:8000)\n\n## Descripción de archivos principales\n\n### src/app/\n- **main.py**: Define la API REST con FastAPI, incluyendo los endpoints para consulta exacta (`/rag/query_exact`), semántica (`/rag/query_semantic`) e indexado (`/rag/index`).\n- **dependencies/**: Proporciona funciones para obtener instancias singleton de los componentes principales (`Retriever` e `Indexer`).\n- **db/**: Lógica de conexión a la base de datos PostgreSQL y utilidades como logging de queries.\n- **schemas/**: Modelos de datos (Pydantic) para las peticiones y respuestas de la API.\n- **middleware/**: Middlewares como el de logging de peticiones y respuestas.\n\n### src/cache/\n- **cache_manager.py**: Lógica para cache exacto y semántico, desacoplada del Retriever.\n\n### src/indexer/\n- **indexer.py**: Lógica para generar embeddings de documentos y almacenarlos en la base de datos usando Google Gemini y pgvector.\n\n### src/retriever/\n- **retriever.py**: Lógica de recuperación RAG. Busca documentos relevantes, gestiona embeddings y consulta el LLM de Gemini para generar respuestas.\n\n### tests/\n- **test_api.py**: Pruebas automáticas para los endpoints principales de la API usando FastAPI TestClient.\n- **test_indexer.py**: Pruebas unitarias para la lógica de indexado de documentos.\n- **test_retriever.py**: Pruebas unitarias para la lógica de recuperación y generación de respuestas.\n\n### docs/\n- **cache_types.md**: Explicación detallada de la diferencia entre exact cache y semantic cache. Consulta este archivo para entender cuándo usar cada tipo de cache y sus ventajas.\n\n- La tabla `prompt_cache` ahora incluye los campos `context` (texto del contexto usado), `context_hash` (hash SHA256 del contexto para comparación robusta) y `prompt_embedding` (embedding del prompt como tipo vector). Si tienes una base de datos previa, deberás migrar la estructura para añadir estos campos.\n\n## Seguridad\n\nEsta API no requiere autenticación. Los endpoints son públicos, pero están protegidos contra abuso mediante rate limiting y CORS. No se almacena información de usuario.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyosoykevin%2Frag-caching-techniques","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyosoykevin%2Frag-caching-techniques","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyosoykevin%2Frag-caching-techniques/lists"}