Referencia de aplicación. Esta es una arquitectura ilustrativa y una lista de comprobación del alcance, no un proyecto de cliente verificado ni una implementación medida. Las tecnologías, el alcance de la integración y los elementos de entrega se acuerdan para el encargo concreto.
Escenario y restricciones
Una empresa que desea respuestas de IA sobre su propia documentación de productos, políticas o historial de soporte. Los requisitos que realmente determinan la arquitectura son: las respuestas deben citar su fuente, el sistema debe decir que no lo sabe en lugar de inventar una respuesta, el coste por conversación debe estar limitado y la calidad debe poder medirse antes y después de cualquier cambio en el prompt o el modelo.
Arquitectura
Capas y responsabilidades
| Capa | Tecnología | Responsabilidad |
|---|---|---|
| Ingesta | Workers de Python | Análisis de documentos, segmentación, generación de embeddings y extracción de metadatos. Se ejecuta como una canalización para que la reindexación sea una operación rutinaria, no una reconstrucción. |
| Almacén vectorial | PostgreSQL + pgvector | Embeddings de segmentos junto con metadatos relacionales. Una base de datos en lugar de un servicio vectorial separado simplifica los permisos y las copias de seguridad a esta escala. |
| Recuperación | Servicio Go | Búsqueda híbrida: similitud vectorial más coincidencia de palabras clave y, después, reranking. La recuperación mediante palabras clave detecta los números de pieza y códigos exactos que los embeddings suelen pasar por alto. |
| Generación de respuestas | Servicio Go que llama a la API del modelo | Ensamblaje del prompt con el contexto recuperado, aplicación obligatoria de citas, respuesta en streaming y presupuesto de tokens por solicitud. |
| Protecciones | Capa de aplicación | Comprobación del alcance, rechazo cuando la confianza de recuperación es baja, filtrado de información personal identificable y escalado a una cola humana. |
| Administración | Panel de administración Vue | Gestión de documentos, activadores de reindexación, revisión de conversaciones, conjunto de evaluación y panel de costes. |
Modelo de datos
Las tablas siguientes contienen las reglas de las que depende todo lo demás. Equivocarse en ellas es lo que convierte una demo funcional en un sistema que no se puede ampliar.
Entidades principales
| Entidad | Campos clave, relaciones y reglas |
|---|---|
| document / version | Documento de origen con historial de versiones y fechas de vigencia, para que una respuesta pueda rastrearse hasta la revisión del documento que la produjo. |
| chunk | Segmento de texto con vector de embedding, ruta de encabezados, recuento de tokens y un puntero al documento y a su posición; la posición es lo que permite que una cita enlace al lugar correcto en vez de al archivo completo. |
| access_scope | Qué roles o tenants pueden recuperar un segmento. El filtrado se realiza dentro de la consulta de recuperación, nunca después de la generación; de lo contrario, el contenido restringido puede filtrarse en una respuesta antes de que se ejecute la comprobación. |
| conversation / message | Historial de turnos con los identificadores de los segmentos recuperados, el modelo utilizado, los recuentos de tokens y la latencia por mensaje, lo que permite atribuir el coste y la calidad a cada conversación. |
| feedback | Valoraciones, correcciones y marcadores de escalado por respuesta, que alimentan el conjunto de evaluación en lugar de desaparecer en un archivo de registro. |
| eval_case | Pregunta, fuente esperada y nota de aceptación. Se ejecuta con cada cambio de prompt o modelo para detectar las regresiones antes de la publicación y no por parte de los clientes. |
Interfaces clave
Endpoints que contienen las reglas de negocio
| Endpoint | Propósito y notas de concurrencia |
|---|---|
| POST /api/v1/ingest | Pone un documento en cola para su análisis, segmentación y generación de embeddings; es idempotente por (document, version), de modo que un reenvío reemplaza al anterior en lugar de duplicarlo. |
| POST /api/v1/chat | Transmite una respuesta. Aplica el alcance de acceso a la recuperación, limita los tokens de contexto, exige citas y devuelve un rechazo cuando la confianza de recuperación está por debajo del umbral configurado. |
| POST /api/v1/chat/{id}/escalate | Entrega la conversación con todo el contexto a una cola humana; es la válvula de escape que mantiene honesto un sistema acotado en lugar de obligarlo a responderlo todo. |
| POST /api/v1/eval/run | Ejecuta el conjunto de evaluación con la configuración actual e informa de la tasa de aprobados y de la precisión de las citas por caso. |
| GET /api/v1/usage | Contabilización de tokens y costes por tenant y por periodo, base para los límites de frecuencia y las alertas presupuestarias. |
Decisiones técnicas
- Recuperación híbrida, no solo vectorial. La recuperación exclusivamente vectorial puede pasar por alto identificadores exactos como números de pieza, códigos de error o referencias de artículos. Compare los enfoques de recuperación con las preguntas de evaluación reales. La coincidencia de palabras clave cubre esa carencia y el reranking combina ambos resultados.
- Citas obligatorias, no solicitadas. Pedir educadamente a un modelo que cite fuentes no es fiable. Las respuestas se validan contra los identificadores de los segmentos recuperados y se rechazan cuando no citan nada; esa es la diferencia entre un sistema en el que se puede confiar y uno que solo parece convincente.
- Umbral de rechazo basado en la confianza de recuperación. Una respuesta errónea expresada con confianza cuesta más que no responder. Por debajo del umbral, el sistema indica que no lo sabe y ofrece escalar la consulta.
- pgvector en lugar de una base de datos vectorial dedicada. Con volúmenes de documentos habituales para una sola empresa, una instancia de PostgreSQL gestiona tanto los vectores como los metadatos, manteniendo las operaciones, los permisos y las copias de seguridad en un solo sistema. Un almacén dedicado solo justifica su complejidad a una escala mucho mayor.
- Conjunto de evaluación desde la primera semana. Sin él, cada cambio de prompt es una suposición y los usuarios descubren las regresiones. Es el control de calidad más económico en un proyecto de IA y el que se omite con más frecuencia.
- Acceso al modelo detrás de nuestro backend. Las claves de API nunca llegan al cliente, y la limitación de frecuencia, los límites presupuestarios y el cambio de modelo permanecen como configuración del servidor en lugar de requerir una publicación de la aplicación.
Objetivos de diseño hipotéticos
Las cifras siguientes son ejemplos hipotéticos de planificación de capacidad, no resultados medidos de clientes, una recomendación de dimensionamiento validada ni un SLA. Establezca objetivos de aceptación específicos para el proyecto después de definir la carga de trabajo, los dispositivos, los datos, el hardware y las dependencias de terceros; verifíquelos mediante un piloto y pruebas de carga antes de comprometerse con un objetivo de producción.
Objetivos de capacidad y rendimiento
| Objetivo | Valor y supuesto |
|---|---|
| Latencia del primer token | Defina un presupuesto hipotético para el primer token y, después, compárelo con el proveedor elegido, la canalización de recuperación y el conjunto de evaluación. La latencia del proveedor está fuera del control de la aplicación; el streaming puede mostrar el progreso sin prometer un tiempo de respuesta. |
| Recuperación | Menos de 200 ms para la búsqueda híbrida más el reranking sobre un corpus situado en el rango bajo de los cientos de miles de segmentos, con un índice pgvector adecuado. |
| Coste por conversación | Limitado mediante un tope de tokens de contexto y un presupuesto por tenant con alertas; la cifra real depende del modelo elegido y de la duración de la conversación, y se mide durante el piloto. |
| Calidad de las respuestas | Se realiza un seguimiento mediante la tasa de aprobados y la precisión de las citas en el conjunto de evaluación. La línea base se establece durante el piloto, en lugar de prometerse por adelantado. |
Qué incluye la entrega
- Código fuente de la canalización de ingesta, los servicios de recuperación y generación de respuestas y el panel de administración en su repositorio
- Esquema de base de datos que incluye las tablas de segmentos, alcance y evaluación, además de la configuración de índices
- Plantillas de prompts y conjunto de evaluación, ambos versionados junto con el código
- Panel de costes y uso, configuración de límites de frecuencia y alertas presupuestarias
- Notas de despliegue, procedimiento de gestión de claves y ruta documentada para cambiar de modelo
Planificación para su empresa
Los módulos anteriores son un punto de partida, no un paquete fijo. Normalmente delimitamos la primera entrega a un flujo de trabajo principal y un flujo de administración, y después ampliamos cuando el uso real muestra dónde están realmente la carga y los casos límite. Envíe un encargo con el alcance definido y lo compararemos con esta arquitectura para indicarle qué partes todavía no necesita.