compañero de Enterprise Document Intelligence, una serie cuya postura es que Enterprise RAG amplifica al experto, no lo reemplaza. La arquitectura se deriva de eso: cuatro ladrillos (análisis de documentos, análisis de preguntas, recuperación, generación), cada uno de los cuales emite piezas escritas que convergen en una llamada de LLM. La industria ahora llama a esa práctica ingeniería de contexto. El alcance aquí es el caso de un solo documento; Las extensiones de corpus, conversación y llamadas de herramientas son trabajos de seguimiento.
📓 Los cuadernos ejecutables están en GitHub: doc-intel/notebooks-vol1.
Cuando se construyen los cuatro ladrillos de un RAG de un solo documento, el conjunto está asentado. El análisis produce tablas relacionales. El análisis de preguntas produce una ParsedQuestion escrita. La recuperación produce un subconjunto filtrado de líneas, además de una auditoría de cómo las seleccionó. Generation produce una respuesta Pydantic con evidencia citada. Todo converge en una llamada de LLM, con un mensaje fijo del sistema y un contenido de usuario ensamblado a partir de piezas anteriores.
Ese oleoducto ahora tiene un nombre. En junio de 2025, Tobi Lütke tuiteó que la “ingeniería rápida” era el marco equivocado y propuso en su lugar “ingeniería de contexto”: “el arte de proporcionar todo el contexto para que la tarea sea plausiblemente solucionable por el LLM”. Andrej Karpathy lo respaldó una semana después como “el delicado arte y ciencia de llenar la ventana de contexto con la información adecuada para el siguiente paso”. En cuestión de meses, el término apareció en la portada de un libro de O'Reilly y LangChain lo estructuró en una taxonomía.
Lo que sigue lee el proceso de RAG de un solo documento a través de esa lente. Cada ladrillo emite piezas mecanografiadas; la etapa de ensamblaje los integra en la convocatoria de LLM; el indicador del sistema permanece fijo para el almacenamiento en caché. Nombrar la práctica no cambia la arquitectura. Cambia cómo llamarlo cuando un auditor pregunta cómo funciona el sistema y le dice al lector que la arquitectura es en la que convergieron los equipos de producción en 2025.
1. El nombre y lo que cubre
Ingeniería rápida solía significar dos cosas relacionadas. Ajustar la redacción de un mensaje para lograr un mejor comportamiento y escribir tomas de ejemplo para que el modelo sepa cómo es un buen resultado. Ambos son estrechos. Se refieren a un bloque de texto enviado a una llamada.
La ingeniería de contexto cubre todo lo que llega a la ventana de contexto del modelo para una llamada:
El indicador del sistema (el rol, las reglas, los ejemplos). Los documentos o filas recuperados. Historial de conversaciones cuando lo hay. Definiciones de herramientas y sus resultados. Memoria, scratchpads, estado del agente. Metadatos estructurados sobre el documento, el corpus, el proyecto. La entrada real del usuario.
En un agente de larga trayectoria que llama al modelo docenas de veces, el mensaje es uno de seis u ocho espacios. El resto proviene de algún lugar anterior: un recuperador, una herramienta, un almacén de memoria, una búsqueda de perfiles. La disciplina cambia de "qué debo escribir en el mensaje" a "qué debo ensamblar en el contexto, de dónde viene cada pieza y cómo mantengo el ensamblaje estable en todas las llamadas".
Eso es trabajo de ingeniería. Parece una arquitectura de software: objetos escritos, contratos entre componentes, pistas de auditoría, almacenamiento en caché. El plazo de 2025 está retrasado, porque la práctica ya existía en los sistemas de producción en funcionamiento. Lütke y Karpathy mencionaron lo que ya estaban haciendo los equipos.
La serie lo ha hecho desde el principio, ladrillo a ladrillo. Las siguientes secciones analizan lo que cada bloque aporta a una carga útil de RAG de un solo documento, luego las cuatro piezas mecanografiadas que llegan a la llamada LLM y el código que produce cada una. Los casos de corpus, conversación y llamadas de herramientas aparecen al final como trabajo fuera de alcance, con indicaciones sobre en qué parte de la serie se abordarán.
2. Cada ladrillo emite contexto escrito
El esquema anterior es el resumen de lo que envió la serie. Cada ladrillo es un emisor de contexto escrito. Los nombres en los cuadros son los campos reales de las clases Pydantic y los DataFrames reales que produce el código.
El análisis emite tablas relacionales y un dictado de síntesis. line_df lleva una fila por línea con bbox. page_df lleva una fila por página con tipo y recuento de columnas. toc_df lleva las entradas del índice con la página de inicio y la profundidad. image_df lleva imágenes incrustadas con phash y metadatos. parsing_summary es la síntesis a nivel de documento: tipo_doc, n_páginas, campos_típicos, resumen, más los campos de mecánica. El bloque de recuperación consume las tablas por fila. El bloque de análisis de preguntas consume el subconjunto semántico de parsing_summary a través de DocContext.
El análisis de preguntas emite una ParsedQuestion. Sus campos no son de forma libre. palabras clave es una breve lista de frases nominales de contenido para su recuperación. La intención es una etiqueta literal de una enumeración fija que impulsa el envío de formas en la generación. estructural_hints.pages_hint lleva páginas fijadas cuando el usuario dijo "en la página 3". respuesta_forma lleva la forma de salida esperada (texto, cantidad, fecha, lista, tabla, dirección) para la búsqueda del esquema de generación. Cada campo es consumido por un ladrillo posterior diferente. Ninguno de ellos se pasa como cadena sin formato al LLM.
La recuperación emite un DataFrame filtrado y un dictado de auditoría. filtered_line_df es el subconjunto de line_df que ve el bloque de generación. Anchor_pages son los ID de página que se conservaron y por qué. Retrieval_audit incluye el método que ganó (palabra clave, TOC, árbitro de LLM), el razonamiento de LLM TOC cuando corresponda y las secciones seleccionadas. El marco filtrado es lo que lee el LLM. La auditoría es lo que lee un auditor.
La generación es un consumidor, no un emisor. Toma la pregunta, las líneas filtradas, el PromptContext y el esquema de respuesta. Llama al LLM. Devuelve una respuesta escrita en Pydantic. El borde discontinuo en el cuadro Generación señala ese rol.
La zona violeta de “ENSAMBLAJE INMEDIATA” a la derecha es donde ocurre la ingeniería de contexto como código. La serie lo implementa mediante tres primitivas:
Un agregador PromptContext(BaseModel) con un campo por fuente de contexto ascendente: doc_context, futuro corpus_context, futuro proyecto_contexto. Un MODULE_SYSTEM_PROMPT fijo a nivel de módulo para cada bloque que llama al LLM. Un MODULE_USER_TEMPLATE con marcadores de posición con nombre que el ladrillo llena a través de str.format(…).
El artículo 1 (el RAG mínimo de cuatro ladrillos) introdujo los ladrillos como un flujo. El artículo 6A (la tesis del análisis de preguntas) hizo que el analizador de preguntas escribiera. El artículo 8A (el contrato de generación tipificado) tipifica el esquema de generación. Este artículo lee los mismos cuatro ladrillos a través de la lente de "qué contexto aporta cada uno, cómo llegan a la convocatoria del LLM sin contaminarse entre sí". Mismo código, diferente lente.
3. Las cuatro partes mecanografiadas de una carga útil de un solo documento
Lo que llega a la convocatoria de LLM para un RAG de un solo documento son cuatro piezas, cada una producida por una pieza de código diferente, cada una con un perfil de costo y caché diferente. Esta sección recorre los cuatro en el orden en que aparecen en el contenido del usuario que lee el LLM.
3.1 El aviso del sistema fijo
La primera pieza es el mensaje del sistema. La descripción del rol, las reglas, los ejemplos. No cambia entre llamadas. La serie lo escribe como una constante de Python a nivel de módulo, luego lo expone como un kwarg con un valor predeterminado para que una persona que llama pueda anular por dominio sin bifurcar:
PARSE_QUESTION_SYSTEM_PROMPT = ( "Extraes frases nominales de contenido de la pregunta del usuario …") def parse_question(question, *, system_prompt: str = PARSE_QUESTION_SYSTEM_PROMPT, user_template: str = PARSE_QUESTION_USER_TEMPLATE, contexto: PromptContext | Ninguno = Ninguno): …
Dos consecuencias operativas. El proveedor LLM puede almacenar en caché el mensaje, ya que no cambia entre llamadas en el mismo modelo. Los datos almacenados en caché cuestan aproximadamente diez veces menos que los datos nuevos en los proveedores que publican una tarifa. Y el aviso es auditable, porque se encuentra en un símbolo estable de Python y un auditor puede realizar búsquedas, versionar y diferenciar entre versiones.
3.2 Las líneas recuperadas, filtradas por el despachador
La segunda parte son las líneas que realmente lee el LLM. El despachador consume ParsedQuestion.keywords y estructural_hints, elige un método (palabra clave, TOC, árbitro LLM) y devuelve el marco filtrado más la auditoría. El contenido del usuario obtiene el marco filtrado; la auditoría se guarda en el disco para que el operador la inspeccione más tarde:
recuperado, filtered_line_df, auditoría = despacho_page_retrieval (pregunta, line_df, page_df, toc_df=toc_df, palabras clave=palabras clave, top_k=5, use_toc=True,)
Lo que se envía al LLM en el contenido del usuario es el marco filtrado, no el documento completo. Un contrato de 200 páginas se convierte en diez páginas de líneas relevantes. El contenido del usuario se mantiene por debajo de unos pocos miles de tokens. La auditoría explica por qué llegó cada página, de modo que una persona que llama puede cuestionar la selección sin volver a ejecutar la llamada.
3.3 El bloque doc-context, JSON compacto
La tercera parte es la síntesis a nivel de documento: tipo de documento, recuento de páginas, campos típicos, resumen. Llega al contenido del usuario como un objeto JSON compacto para que el LLM pueda analizar textos ambiguos en comparación con la naturaleza del documento. La serie lo implementa como un método en cada clase Pydantic que transporta contexto. DocContext.as_prompt_json() construye el JSON más pequeño que aún nombra los cuatro campos; Los valores nulos y vacíos se eliminan:
clase DocContext(BaseModel): doc_type: str | Ninguno = Ninguno n_páginas: int | Ninguno = Ninguno campos_típicos: lista[cadena] =[]resumen: cadena | Ninguno = Ninguno def as_prompt_json(self) -> str: payload = {k: v para k, v en self.model_dump().items() si v no es Ninguno y v!=[]} return json.dumps(carga útil, separadores=(",", ":"))
Medido en un CV con doc_type="resume", n_pages=1 y cuatro campos típicos, la carga útil tiene menos de 200 caracteres. En un documento desconocido donde todos los campos son nulos o están vacíos, la carga útil es el objeto vacío {} y el bloque se omite por completo del contenido del usuario. El mismo patrón se aplica a los espacios reservados de contexto de corpus y contexto de proyecto cuando los artículos posteriores los activan.
3.4 El agregador PromptContext que incluye los tres anteriores
La cuarta pieza es el agregador. Cada bloque de llamada de LLM toma un contexto opcional: PromptContext kwarg. El agregador lleva el contexto del documento en su propio espacio escrito hoy, con espacios reservados para el contexto del corpus y el contexto del proyecto que activarán los artículos siguientes. El asistente render_context_block(context) recorre los campos no nulos y emite un bloque JSON etiquetado por capa al principio del contenido del usuario:
clase PromptContext(BaseModel): doc_context: DocContext | Ninguno = Ninguno # corpus_context: CorpusContext | Ninguno = Ninguno # reservado # contexto_proyecto: ContextoProyecto | Ninguno = Ninguno # reservado
Cada bloque LLM toma un contexto opcional: PromptContext kwarg. El asistente render_context_block(context) recorre cada campo no nulo, representa su JSON compacto y emite un bloque etiquetado por capa. Agregar una nueva capa significa descomentar un campo, agregar dos líneas en el asistente y cada ladrillo elige la nueva capa de forma gratuita. La firma es estable en todas las versiones.
4. ¿Qué cambios en la práctica?
Nombrar la práctica cambia tres cosas operativas, incluso si el código no cambia.
Auditoría. Cuando la respuesta es incorrecta, la pregunta ya no es "¿qué decía la pregunta?". La pregunta es "qué apareció en la ventana de contexto de esa llamada". La serie conserva cada salida de bloque en el disco: parsing/, questions//parsed_question.json, retrieval//retrieved_pages.parquet, retrieval//retrieval_audit.json. El auditor reconstruye la carga útil del contexto a partir de esos archivos. Entonces la pregunta se vuelve específica: ¿el doc_context era incorrecto?, ¿se seleccionaron las páginas incorrectas?, ¿el sistema indicaba cambios entre versiones?, ¿la plantilla de usuario estaba obsoleta? Cada uno de ellos tiene una solución diferente.
Costo. Compuesto de dos palancas. El aviso del sistema se fija en todas las llamadas del mismo modelo, por lo que paga una tarifa de entrada en caché. El contenido del usuario se ha comprimido mediante as_prompt_json y se ha seleccionado mediante recuperación, por lo que la parte variable es pequeña. En un corpus de 100 documentos con 10 preguntas cada uno, el coste dominante es la parte variable multiplicada por 1.000 llamadas. Nombrar la práctica no cambia las matemáticas, pero hace que el presupuesto para cada llamada sea legible: cada línea en la carga útil del contexto tiene un generador al que alguien puede señalar.
Composición del trabajo de seguimiento. El agregador PromptContext tiene un campo activado hoy, con dos más reservados para las capas de contexto de corpus y contexto de proyecto que se agregan en una parte posterior de la serie. Cuando lleguen, este artículo no necesitará ser reescrito. La firma permanece. El cuerpo de render_context_block crece una rama. Cada ladrillo que ya tiene contexto: PromptContext | Ninguno recoge el nuevo subcontexto de forma gratuita. La disciplina vale la pena al diferir las roturas entre versiones.
5. Fuera de alcance, con sugerencias
El caso del documento único termina aquí. La ingeniería de contexto en general cubre tres cosas que este artículo no aborda:
Contexto del corpus. Cuando la respuesta requiere leer muchos documentos, el LLM necesita tener una idea de qué documentos están dentro del alcance y qué tienen en común. Eso vive en un futuro CorpusContext Pydantic, alimentado por un agregador sobre valores parsing_summary por documento. El espacio está reservado en PromptContext para que las firmas de los ladrillos no cambien. Un artículo posterior analiza la construcción y el cableado del consumidor. Historial de conversaciones. El chat de varios turnos incluye pares de preguntas y respuestas anteriores que el LLM debe considerar antes de responder la nueva pregunta. Se trata de un problema de Estado (dónde vive la historia, cuándo se resume, cuándo se poda) además de un problema de contexto. Un artículo posterior de la serie lo trata como un ladrillo de primera clase. Llamadas a herramientas. Los bucles de agentes traen definiciones de herramientas, resultados de herramientas y estados intermedios a la ventana contextual. Los problemas de selección/compresión/aislamiento se agudizan allí porque la ventana de contexto se llena rápidamente en los turnos. Un artículo posterior de la serie trata la ingeniería de contexto agente como su propio tema.
Las cuatro estrategias canónicas que los nombres del blog de LangChain (escribir, seleccionar, comprimir, aislar) se desarrollaron teniendo en cuenta el bucle del agente. Dos de ellos (escribir y seleccionar) se traducen claramente al caso de un solo documento como el indicador del sistema y el despachador de recuperación. Los otros dos (comprimir y aislar) se aplican en espíritu, pero son más duros una vez que el corpus y la conversación entran en escena, razón por la cual este artículo no fuerza el mapeo de cuatro vías.
verlo en vivo
Un breve compañero en vivo corre en el tablero del shipai. Haga clic en cualquier página candidata en el seguimiento de auditoría, luego haga clic en ancla/párrafo/sección/página en el selector de arriba.
El mismo ancla, cuatro opciones de alcance contextual una al lado de la otra. El ancla es una línea. El párrafo tiene ±5 líneas en la misma página. La sección utiliza el TOC para ampliar al cuerpo de la sección. La página ocupa toda la página. La compensación del artículo (costo versus precisión) se convierte en un control deslizante que puede sentir en un PDF real en lugar de en un párrafo de prosa.
6. Conclusión
La conversación de la industria de 2025 sobre la ingeniería de contexto le da un nombre a una disciplina que RAG de documento único ya practica ladrillo a ladrillo. El análisis emite tablas relacionales y una síntesis a nivel de documento. El análisis de preguntas emite una ParsedQuestion escrita cuyos campos impulsan cada uno un bloque descendente diferente. La recuperación emite un conjunto de líneas filtradas más una auditoría. La generación consume la carga útil ensamblada a través de un mensaje fijo del sistema, un contenido de usuario con plantilla y un agregador PromptContext con una ranura escrita por capa ascendente.
La etiqueta es lo que cambia: un auditor, un gerente de contratación o un proveedor que lea la arquitectura puede colocarla dentro del vocabulario de 2025 sin necesidad de traducción adicional. Los ladrillos, los esquemas y las compensaciones entre costo y caché no cambian. El corpus, la conversación y los casos de llamada de herramientas surgen como trabajo de seguimiento, cada uno con su propio espacio escrito reservado en el mismo agregador.
7. Fuentes y lecturas adicionales
La conversación de 2025, en orden cronológico.
Walden Yan, No construyas agentes múltiples, Cognition, 12 de junio de 2025. El primer artículo que da nombre a la disciplina. La afirmación de Yan de que “la ingeniería de contexto es efectivamente el trabajo número uno de los ingenieros que construyen agentes de IA” es la frase que Lance Martin cita más tarde cuando presenta la taxonomía de las cuatro estrategias. Tobi Lütke, X, 18 de junio de 2025. El tweet del nombre: "Me gusta mucho el término 'ingeniería de contexto' en lugar de ingeniería rápida. Describe mejor la habilidad principal: el arte de proporcionar todo el contexto para que la tarea sea plausiblemente solucionable por el LLM". Lance Martin, Ingeniería de contexto para agentes, 23 de junio de 2025. El artículo de taxonomía. También publicado nuevamente en el blog de LangChain con la firma del equipo LangChain. Andrej Karpathy, X, 25 de junio de 2025. El respaldo: "+1 para 'ingeniería de contexto' sobre 'ingeniería rápida'. Las personas asocian indicaciones con descripciones breves de tareas que le daría a un LLM en su uso diario. En cada aplicación LLM de potencia industrial, la ingeniería de contexto es el delicado arte y la ciencia de llenar la ventana de contexto con la información adecuada para el siguiente paso". Drew Breunig, Cómo arreglar su contexto, 26 de junio de 2025. Una taxonomía paralela: seis tácticas concretas (RAG, carga de herramientas, cuarentena de contexto, poda de contexto, resumen de contexto, descarga de contexto) para mantener la ventana de contexto en buen estado.
Las taxonomías, una al lado de la otra.
Lance Martin: cuatro estrategias para el bucle de agentes (escribir, seleccionar, comprimir, aislar). RAG de documento único traduce los dos primeros claramente; los otros dos muerden con más fuerza una vez que el corpus y la conversación entran en escena. Drew Breunig: seis tácticas (RAG, carga de herramientas, cuarentena de contexto, poda, resumen, descarga). Más detallado, menos abstracto. Útil cuando el bucle del agente ya se está ejecutando y la ventana de contexto se está llenando.
Los tratamientos más largos.
Contrapuntos.
Weaviate, libro electrónico Context Engineering (23 p, diciembre de 2025). El marco del proveedor: seis componentes (agentes, aumento de consultas, recuperación, técnicas de indicación, memoria, herramientas). La posición de la serie sobre este cambio de marca, donde el reetiquetado sigue la línea de productos en lugar de la práctica, se trata en una publicación de crítica de seguimiento. Blog de Roadie, Por qué combinar RAG con ingeniería de contexto le cuesta en producción. El marco opuesto: mantener RAG y la ingeniería de contexto distintas, con la recuperación como una ranura entre muchas.
La serie primitiva a la que hace referencia este artículo.
Agregador PromptContext y proyección DocContext: src/docintel/core/schemas/. Ayudante render_context_block: src/docintel/core/prompts.py. Avisos del sistema a nivel de módulo y plantillas de usuario: cada módulo de llamada LLM en src/docintel/, por convención. Anteriormente en la serie: Amplifique al experto: una filosofía para crear RAG empresarial. El manifiesto de la serie: los cuatro ladrillos (análisis, análisis de preguntas, recuperación, generación) están diseñados para escalar el juicio del experto, no para reemplazarlo.
Parte I: Lo que funciona, lo que no funciona
Baseline Enterprise RAG, desde PDF hasta respuesta resaltada. El canal de cuatro ladrillos de un extremo a otro: PDF de entrada, respuesta resaltada de salida. Las incrustaciones no son mágicas: los modos de falla predecibles de la recuperación de RAG. Dónde gana la incorporación de similitud (sinónimos, errores tipográficos, paráfrasis), dónde predeciblemente se rompe (términos desconocidos, negación, relevancia de término versus respuesta) y cómo usarlo de todos modos. RAG no es aprendizaje automático y el conjunto de herramientas de ML resuelve el problema equivocado. Por qué los barridos y ajustes de tamaño de fragmentos optimizan lo incorrecto; en su lugar, ruta por tipo de pregunta. De expresiones regulares a modelos de visión: qué técnica RAG se adapta a qué problema. Dos ejes, complejidad documental y control de preguntas, que seleccionan la técnica para cada caso.
Parte II: Los cuatro ladrillos
Análisis de documentos
Más allá de extract_text: las dos capas de un PDF que impulsan la calidad RAG. La primera mitad del bloque de análisis: la naturaleza del documento, las señales y el resumen. Deje de devolver texto plano desde un PDF: las tablas relacionales que RAG necesita. La segunda mitad del bloque de análisis: las tablas relacionales que lee cada bloque posterior. Cuando PyMuPDF no puede ver la tabla: analice archivos PDF para RAG con Azure Layout. Las mismas tablas de Azure Layout: celdas de tabla nativas, OCR, roles de párrafo. Analice archivos PDF para RAG localmente con Docling: tablas enriquecidas, sin carga en la nube. Las mismas tablas calculadas localmente con Docling: celdas de TableFormer, nada sale de la máquina. Los Vision LLM también son analizadores de PDF: leen cuadros y diagramas para RAG. Visión como analizador: las imágenes se convierten en texto buscable. Analice archivos PDF escaneados para RAG con EasyOCR: el OCR gratuito le proporciona palabras, no un documento. Donde termina el OCR tradicional: texto recuperado, estructura perdida. Hacer que las imágenes de un PDF puedan buscarse en RAG, sin pagar para leerlas todas. La cascada de imágenes: filtrar barato, clasificar, describir sólo lo que vale la pena leer. Reconstruir la tabla de contenido que un PDF olvidó enviar, para que RAG pueda analizarlo por sección. Reconstruir toc_df cuando el PDF imprime una página de contenido pero no incluye ningún esquema.
análisis de preguntas
Analice la pregunta antes de buscar: el paso que falta en la mayoría de los procesos de RAG. La tesis del análisis de preguntas: por qué una cadena de usuario necesita el mismo análisis que un documento y cómo se divide en un resumen de recuperación y un resumen de generación. Cinco campos que RAG debe extraer de cualquier pregunta: palabras clave, alcance, forma, descomposición, aclaración. Las cinco familias de columnas que el analizador lee directamente de la pregunta del usuario, con el código que completa cada una. Una pregunta RAG analizada, cuatro decisiones: estrategia de fragmentos, nivel de modelo, fragmentos, pista de auditoría. Las decisiones que toma el analizador sobre la cadena de usuario, utilizando el perfil del documento: envío, activaciones, esquema completo, seguimiento de auditoría (pipeline_trace.json) y un recorrido por el corpus del corredor.
Recuperación