Inteligencia artificial
para explorar
bibliotecas y tesis.

La pregunta del laboratorio es cómo transformar fichas bibliográficas y texto de tesis en fuentes consultables, y cómo usar esas fuentes para apoyar una respuesta. El resultado disponible es un sistema ejecutable y trazable. Determinar cuánto mejora la relevancia o el trabajo de una biblioteca exige otra etapa: una evaluación con personas y criterios definidos.

Para comenzar sin conocimientos de IA, conviene distinguir cinco acciones. Preparar convierte datos a una estructura consistente. Indexar organiza esa estructura para encontrar resultados. Entrenar modifica parámetros a partir de ejemplos y una pérdida. Vectorizar aplica una transformación ya fijada y guarda números por texto. Generar produce texto nuevo a partir de una pregunta y un contexto. En este proyecto sólo el entrenamiento del encoder de títulos ajustó una red; las otras acciones tienen objetivos diferentes.

Cada apartado conecta entrada → operación → parámetros → archivo de salida → comprobación. Los bloques de código identificados como literales proceden de las funciones citadas. Los ejemplos abreviados, fórmulas pedagógicas y comandos para otra instalación se indican como tales: no son registros de nuevas ejecuciones.

Las cifras de datos se contrastaron con artifacts/entrega-servidor-entrenada-v1/payload/BUILD_REPORT.json, los manifiestos, las bases SQLite y sectesis/neural/encoder.json. La Release privada de artefactos conserva el código de preparación 9193ce88f586783d3d8ab5dd93ec6880f49116a9. Las citas de funciones se fijan al commit auditado de código 01bbc0c, para que futuras ediciones de main no desplacen sus líneas. La revisión del manual no ejecuta un nuevo entrenamiento.

GitHub solicita acceso al repositorio privado para abrir esas fuentes. Los extractos y explicaciones de esta página permiten seguir el proceso sin ese acceso. Los registros operativos locales no están publicados como si fueran datos del repositorio. Una prueba de integridad demuestra que los bytes coinciden; una prueba funcional demuestra que una operación responde; ninguna equivale por sí sola a calidad científica o validación humana.

Ruta de lectura: comenzar con los conteos y el diagrama; recorrer TXT, PDF, BM25, entrenamiento y vectores; después estudiar la consulta, la evaluación y Llama. Las secciones de API y servidor explican la operación. Al final se presentan aportes, investigación pendiente y un mapa de archivos para continuar leyendo el código. El glosario permite consultar los términos durante ese recorrido.

Volver al índice ↑

El proyecto aplica recuperación de información, aprendizaje automático e IA generativa a datos bibliográficos y a fragmentos de tesis. Un catálogo es una parte de los datos de una biblioteca: describe documentos mediante título, autores, año, materias y enlaces. Un PDF aporta texto del documento. Por eso la presentación principal habla de IA aplicada a datos de bibliotecas y tesis, y el buscador distingue ambas colecciones.

IATESIS es el nombre del proyecto, elegido por su autor, Víctor Manuel Osornio Luna, alumno del Diplomado en Inteligencia Artificial Aplicada, 6.ª emisión, DGTIC UNAM. La presentación y el pie de página identifican al estudiante y su formación. El proyecto utiliza la fuente bibliográfica sectesis.txt; de ella proceden el identificador técnico SECTESIS, los IDs sectesis:…, las rutas /api/v1/sectesis y las variables SECTESIS_*. Estos nombres técnicos se conservan para mantener la compatibilidad de los datos, la API y las instalaciones existentes. SECTESIS identifica esa fuente y su implementación previa; no es una técnica de IA ni el nombre visible actual del proyecto. El proyecto no implementa todos los procesos de una biblioteca: circulación, adquisiciones y administración de usuarios quedan fuera de este buscador.

El resultado esperado para una persona es encontrar referencias o pasajes, abrir sus fuentes y, opcionalmente, pedir una redacción apoyada en ellos. Para una biblioteca, aporta un índice reutilizable, acceso a texto extraído y trazabilidad por documento y página. Que encuentre resultados no demuestra por sí solo que sean los más relevantes.

Volver al índice ↑

De los PDF, 17 quedaron con estado text_extracted, 32 con partial_text y uno con no_extractable_text. Hubo 202 páginas sin texto y 105 con menos de 25 letras: esas 307 páginas no generaron fragmentos. Que un PDF esté indexado no significa que todo su contenido haya sido interpretado.

El archivo conserva el nombre histórico sample.jsonl, pero en esta entrega contiene 593.067 registros porque se preparó con --sample 0. El entrenamiento del encoder se ejecutó en este servidor: cuatro épocas, con selección de la tercera por pérdida de validación. No corresponde describirlo como un laboratorio de 12.000 registros simplemente importado.

Volver al índice ↑

La consulta selecciona catálogo o PDF; la búsqueda híbrida combina dos métodos dentro de la colección elegida. No une automáticamente una ficha y un archivo PDF ni busca simultáneamente en ambas colecciones.

Volver al índice ↑

Entrada y objetivo: entender una ficha antes de calcular números

La entrada es sectesis.txt, una exportación bibliográfica ALEPH secuencial de 866.475.615 bytes. Contiene fichas que describen tesis, no la transcripción de todas ellas. El objetivo de esta etapa es convertir esas líneas en registros con campos consistentes y conservar su procedencia. No interviene Llama ni se aprenden pesos.

records() lee UTF-8 estricto y agrupa líneas consecutivas por el identificador de nueve dígitos. El formato exige ese ID, una etiqueta de cinco posiciones, la letra L y el contenido; $$ separa subcampos. Una línea no interpretada se registra como anomalía cuando ya hay un registro en curso. La implementación supone que las líneas de una ficha son contiguas. Parser real: ingest.py, líneas 8–35.

LINE = re.compile(r"^(\d{9}) (.{5}) L ?(.*)$")
SUB = re.compile(r"\$\$([^$])([^$]*)")

Fragmento real del TXT:

000000001 1001  L $$aAceves Ramirez, Noe de Jesus$$esustentante
000000001 24510 L $$aOrigen, causas, evolución, perspectivas y soluciones propuestas al problema habitacional en México /$$ctesis que para obtener el título de Arquitecto, presenta Noe de Jesus Aceves Ramirez
000000001 502   L $$bLicenciatura en Arquitectura$$cUniversidad Nacional Autónoma de México,$$d1979$$gFacultad de Arquitectura,

canonical() transforma las etiquetas en un objeto con campos conocidos. Las prioridades siguientes son reglas del software, no correcciones hechas por una persona:

Reglas literales: canonical(), líneas 37–68.

Selección de campos del registro canónico real —el objeto completo contiene más—:

{
  "id": "sectesis:000000001",
  "source_id": "000000001",
  "title": "Origen, causas, evolución, perspectivas y soluciones propuestas al problema habitacional en México",
  "authors": ["Aceves Ramirez, Noe de Jesus"],
  "year": 1979,
  "faculty": "Facultad de Arquitectura",
  "degree": "Licenciatura en Arquitectura"
}

Tres operaciones distintas de normalización

La clave de deduplicación del entrenamiento es fold(título), no una lista de tokens. Dos títulos que sólo se diferencian por puntuación pueden seguir siendo distintos para esa regla. No hay lematización —reducción a una forma de diccionario— ni identificación de duplicados semánticos. Limpieza y clave: ingest.py, 10–13; tokens del proyecto: search.py, 6–7.

Preparación completa, control de calidad y salida

prepare() escribe un objeto por línea en sample.jsonl y el perfil en profile.json. La CLI básica tiene --sample 12000 por defecto; esta entrega conserva todo el TXT, como acredita sample_method=full_corpus y sample_size=593067. --sample 0 significa corpus completo. Una muestra positiva usa reservoir sampling: recorre todo el origen y conserva una selección uniforme, no las primeras filas. El perfil también se calcula sobre todo el origen leído. Preparación: ingest.py, 85–117.

El perfil real reporta 13 registros sin título, 17 sin autor, 1.828 sin año, 31.687 sin facultad y 296 sin grado. Marca 1.827 años para revisión y 87 líneas no interpretadas. Sólo 2 registros tienen resumen según el parser; 193.503 tienen materias. Estas son medidas de presencia y banderas automáticas, no una certificación catalográfica. Los registros incompletos permanecen en el catálogo; otro filtro decide después cuáles sirven para entrenar. Evidencia: payload/sectesis/profile.json de la entrega.

Cada registro contiene dos textos preparados para usos diferentes. Fragmento literal de canonical():

rec['semantic_text']='\n'.join(v for v in [title, '; '.join(subjects),abstract] if v)
rec['lexical_text']='\n'.join(v for v in [title,'; '.join(rec['authors']),'; '.join(subjects),degree,faculty,year_raw] if v)

lexical_text se usa para BM25. Aunque exista semantic_text, el encoder didáctico activo recibe el título, no todo ese campo. record_sha256 identifica los campos parseados de la ficha; es distinto del hash de bytes del TXT y del ID bibliográfico.

De JSONL a SQLite: guardar e indexar no es entrenar

search.build() inserta cada registro en records, con ID, ámbito, año, facultad y JSON. Crea docs, una tabla virtual FTS5 para el índice invertido, y manifest, con versión, conteo y huella del JSONL. SQLite organiza texto y términos para recuperarlos; no aprende la matriz neuronal. Construcción exacta: search.py, 13–30.

con.execute('CREATE TABLE records(id TEXT PRIMARY KEY,tenant TEXT NOT NULL,year INTEGER,faculty TEXT,payload TEXT NOT NULL)')
con.execute("CREATE VIRTUAL TABLE docs USING fts5(id UNINDEXED,title,body,tokenize='unicode61 remove_diacritics 2')")

FTS5 utiliza su propio tokenizer unicode61. Al construir docs, se guarda el texto documental completo: no se recorta cada documento a los 64 tokens del encoder. El ID no se indexa como texto; sirve para enlazar el resultado con su registro. La salida real es sectesis/catalog.sqlite. El procedimiento rechaza una ruta ya existente y publica el archivo temporal al terminar, para conservar una versión coherente.

Volver al índice ↑

Qué es un fragmento y por qué se utiliza

Un fragmento, o chunk, es un tramo de texto extraído de una página que se guarda como unidad de búsqueda. Es texto del documento, no un resumen escrito por Llama ni un archivo PDF nuevo. Una página puede producir varios fragmentos y una tesis muchos; por eso 6.541 fragmentos no equivalen a 6.541 tesis.

Se divide el texto para recuperar pasajes más precisos y enviar a la generación sólo material pertinente, en lugar de una tesis completa. Cada fragmento conserva el archivo, la página y sus posiciones para volver a la fuente. Dividir también tiene un coste: puede separar ideas o dejar una explicación fuera del pasaje; por eso se conserva algo de texto compartido entre fragmentos consecutivos.

Cómo se crearon en este proyecto

PyMuPDF abre cada PDF y extrae el texto disponible por página con page.get_text("text", sort=True). Se normalizan espacios y caracteres de control. No se añaden resúmenes generados ni se ejecuta OCR. Si el PDF ya contiene una capa de texto defectuosa, esa extracción puede conservar errores; un PDF escaneado sin texto puede no aportar fragmentos.

Las páginas se dividen en fragmentos de hasta 1.600 caracteres, con un solapamiento objetivo de 200 caracteres, ajustado en límites de palabras. No se mezclan páginas. Se exige un mínimo de 25 letras en la página. Los desplazamientos char_start y char_end se refieren al texto normalizado de esa página; el extremo final es exclusivo.

Ejemplo real de 0609550.pdf, página física 33:

Realizar la planeación, programación y evaluación periódica de las actividades que se efectúan mediante el análisis de la situación de las diferentes áreas.

Es una vista abreviada: corresponde a las posiciones 562–718 dentro de un fragmento de 1.596 caracteres. No es el texto completo del fragmento. Metadatos reales:

{
  "id": "pdf-61d5c568d55a2a6b6620dcc56b7eaae1925b3241837a5180719e3561681a611d:p33:c0",
  "doc_id": "pdf-61d5c568d55a2a6b6620dcc56b7eaae1925b3241837a5180719e3561681a611d",
  "file": "0609550.pdf",
  "page": 33,
  "char_start": 0,
  "char_end": 1596
}

doc_id concatena pdf- y el SHA-256 de los bytes originales. p33 identifica la página física; c0 el primer fragmento de esa página, numerado desde cero. Un cambio de bytes cambia la identidad del documento. Con iguales bytes, extractor y opciones, la segmentación es reproducible. El ejemplo TXT y este PDF son documentos distintos; no se está afirmando una relación entre ellos.

Se producen dos representaciones del mismo conjunto: pdf/chunks.jsonl facilita inspección e intercambio y pdf/catalog.sqlite permite búsqueda. En SQLite, files guarda documentos, chunks guarda IDs y páginas, y fts indexa el texto de los fragmentos. Un manifest.json registra archivos omitidos, conteos, opciones y hashes. Los originales permanecen en data/PDF; no se convierten en pesos ni se sustituyen por SQLite.

Dos fragmentos consecutivos reales

En 0609550.pdf, la página física 33 produjo estas dos unidades, comprobadas directamente en SQLite. Comparten el mismo doc_id mostrado arriba:

La franja 1.396–1.596, de 200 caracteres, aparece en ambos. El segundo es más corto porque llega al final del texto de esa página. Esas posiciones cuentan caracteres del texto normalizado, no bytes del PDF ni tokens de Llama. En otras páginas, el ajuste al límite de palabra puede cambiar la longitud y el solapamiento efectivos.

El código busca un espacio para no cortar una palabra cuando alcanza el tamaño objetivo, guarda el tramo y retrocede hacia la zona de solapamiento para empezar el siguiente. No detecta automáticamente capítulos ni garantiza cortes por oraciones completas. Cada página se procesa por separado; no se repite texto de la página anterior dentro de la siguiente.

Cada unidad se escribe en chunks.jsonl y en SQLite con el mismo ID. BM25 indexa su texto; la vectorización aplica el encoder fijo y guarda una fila de 1.024 valores asociada a ese ID. La búsqueda devuelve el fragmento con su página y enlace al original. El encoder activo sólo usa hasta 64 tokens útiles, de modo que un fragmento puede estar completamente disponible para BM25 y la lectura humana, pero representado parcialmente en la búsqueda densa.

Código: extract, chunks e index_pdfs.

Parámetros aplicados, justificación y cobertura observada

El tamaño 1.600 y el solapamiento 200 son decisiones de esta implementación: acotan el pasaje y conservan algo de continuidad. No se realizó una comparación que demuestre que sean óptimos. El archivo pdf/manifest.json de la entrega confirma estas opciones y PyMuPDF 1.26.7.

Definición y validación: Options y validate. Opciones realmente expuestas por el comando: main: index y vectorize. Un valor en el código Python no equivale automáticamente a una opción disponible en la pantalla o en Compose.

Este fragmento literal del algoritmo muestra el corte. Busca el último espacio en la segunda mitad del tramo para evitar partir una palabra. El código siguiente a este fragmento ajusta también el comienzo de la siguiente unidad:

end = min(start + size, len(text))
if end < len(text):
    boundary = text.rfind(" ", start + size // 2, end)
    if boundary > start:
        end = boundary
yield start, end, text[start:end]
if end == len(text):
    break
next_start = max(start + 1, end - overlap)

Fuente: chunks, líneas 49–67. La normalización usa NFC y colapsa espacios; conserva mayúsculas, acentos y palabras con guiones. No hace lematización ni recompone automáticamente palabras cortadas al final de línea: normalize.

En la entrega final se reconstruyeron los archivos del índice reutilizando la extracción anterior de 49 documentos, según files_reused=49. No se extrajeron de nuevo esos 49 PDF durante ese build. Para reutilizar, index_pdfs exige la misma huella de extractor/opciones y el mismo SHA-256 de cada original; después escribe el nuevo SQLite y JSONL. La vectorización sí aplica los pesos fijos del encoder de la entrega a esos fragmentos. Código: index_pdfs: reutilización por huella y vectorize: inferencia con pesos existentes.

El manifest suma 202 páginas sin texto y 105 con menos de 25 letras: 307 de las 5.034 páginas no originaron fragmentos. Las 4.727 restantes produjeron 6.541 unidades. Por tanto, «49 PDF indexados» significa cobertura parcial o total del texto extraíble de esos archivos, no lectura íntegra garantizada. Los títulos obtenidos de metadata PDF tampoco son metadatos bibliográficos validados. Fuente de las reglas y estados: extract: extracción por página y estados; evidencia de esta ejecución: pdf/manifest.json incluido en la Release de artefactos.

El indexador omite enlaces simbólicos, contenido duplicado y archivos que exceden límites; respeta el permiso de copiar texto y no abre archivos que requieren clave. Verifica que el original no cambie durante la extracción y publica en un destino nuevo. Estas comprobaciones protegen la coherencia de los datos; no interpretan imágenes, tablas o fórmulas: index_pdfs: controles e índice nuevo.

Volver al índice ↑

BM25 —Best Matching 25— es un método de ranking léxico: ordena coincidencias entre palabras de la consulta y texto indexado. Se eligió como referencia de recuperación implementable sin entrenamiento neuronal y capaz de buscar términos presentes en los datos. Su existencia en el laboratorio permite comparar la búsqueda densa con un método léxico real; no demuestra que uno sea superior en todas las preguntas.

Qué entra al índice y qué entra a la consulta

El catálogo guarda title y body en la tabla virtual FTS5 docs; body contiene título, autores, materias, grado, facultad y año original. El ID queda UNINDEXED: sirve para unir el resultado con su ficha. PDF usa la tabla fts, con el texto completo de cada fragmento y su ID sin indexar. Ambos declaran tokenize='unicode61 remove_diacritics 2'. Código aplicado: build: columnas y carga del catálogo y index_pdfs: esquema PDF.

Hay dos tokenizadores distintos. FTS5 indexa todo el texto que se guarda en sus columnas. La función Python tokens() prepara la consulta y también las entradas del encoder: normaliza mayúsculas y acentos, descarta palabras de parada y términos de dos caracteres o menos, y conserva los primeros 64 términos útiles. Por tanto, el límite 64 no recorta el texto almacenado en el índice BM25. No se aplicó stemming, lematización ni expansión por sinónimos.

Código literal de tokens, con su lista de palabras excluidas:

STOP=set('de la el los las en y a un una para por con del al que sobre entre como su se es tesis estudio analisis'.split())
def tokens(s):return [w for w in re.findall(r'\w+',fold(s)) if len(w)>2 and w not in STOP][:64]

Fuentes: tokens, líneas 6–7 y fold: normalización Unicode. Ejemplo didáctico: El problema habitacional en México produce problema, habitacional, mexico. El código forma "problema" OR "habitacional" OR "mexico"; basta coincidir con parte de la consulta. La pantalla no ofrece una sintaxis avanzada de frases, AND o sinónimos aunque FTS5 tenga capacidades adicionales.

Cómo se calcula y ordena la puntuación

La contribución de cada término depende de su frecuencia en el documento, su rareza en la colección y la longitud del documento. La repetición se satura: cien apariciones no aportan cien veces más utilidad. Para entender el cálculo positivo mostrado por esta API:

aporte = IDF × f × (k1 + 1) / (f + k1 × (1 - b + b × longitud / longitud_media))
score = suma de aportes de los términos consultados

f es frecuencia ponderada por columna; IDF expresa rareza, y longitud cuenta tokens FTS. FTS5 fija internamente k1=1,2 y b=0,75; no son argumentos de este buscador. SQLite devuelve el signo inverso para ordenar de menor a mayor y nuestra API lo cambia al publicar. La definición exacta de FTS5 especifica su IDF y la ponderación por columna.

El título del catálogo participa en su columna y también en body; no interpretar el peso 2 como una garantía de «doble relevancia» de una tesis. Los filtros de año excluyen fichas sin año cuando no pueden satisfacer la condición. La facultad se compara completa tras normalización, no por coincidencia parcial. PDF no tiene filtros de año ni facultad en esta API. Fuentes: LexicalIndex.search, Engine.lexical y Query: límites de la API.

Este SQL es una presentación equivalente de la consulta implementada, con valores ilustrativos y sin filtros opcionales:

SELECT r.payload, bm25(docs, 0, 2, 1)
FROM docs JOIN records r ON r.id = docs.id
WHERE docs MATCH ? AND r.tenant = ?
ORDER BY bm25(docs, 0, 2, 1), r.id
LIMIT ?;
-- Parámetros: '"problema" OR "habitacional" OR "mexico"', 'global_unam', 5

LexicalIndex.search añade filtros mediante parámetros SQL; Llama no escribe ni ejecuta esa consulta. El índice busca coincidencias de los datos existentes: que una ficha incluya «México» no prueba que responda toda la pregunta. El score BM25 no es una probabilidad ni un porcentaje de verdad y no debe sumarse directamente con el coseno de otro método.

Qué se podría comparar en investigación

Quedan como experimentos propuestos: OR frente a coincidencia de todos los términos, otras ponderaciones de título/cuerpo y normalización lingüística. Exigen cambios de código o nuevos índices, casos de relevancia revisados y comparación con esta configuración fija. No se ejecutaron esas variantes ni se eligieron los valores actuales mediante una optimización de relevancia del catálogo completo.

Volver al índice ↑

Qué significa entrenar en este laboratorio

Entrenar consiste en modificar una matriz de números, W, para reducir una función de pérdida. La entrada es la representación TF-IDF de un título; la salida es un vector de 1.024 coordenadas. El modelo aprende a aproximar dos versiones incompletas del mismo título y distinguirlas de otros títulos del lote. No aprende de preguntas respondidas por bibliotecarios ni de párrafos PDF. Es una red lineal didáctica construida desde cero, sin conocimiento lingüístico preentrenado.

El proceso histórico quedó registrado en BUILD_REPORT.json, sectesis/neural/encoder.json, training_sample.jsonl y splits.json. El kit declara training.performed=true, cuatro épocas y la tercera como seleccionada. En esta revisión del manual se verificaron esos archivos; no se repitió el entrenamiento. El código de ingesta y encoder conserva las mismas huellas que la construcción del commit 9193ce88f586783d3d8ab5dd93ec6880f49116a9.

Paso 1: elegir datos, filtrar y separar particiones

reservoir() recorre el JSONL completo y selecciona 12.000 registros con semilla 20260909. Cada registro tiene la misma oportunidad de entrar, pero no se garantiza equilibrio por facultad o año. El orden de entrada también importa para reproducir la muestra. Selección: ia_artefactos.py, 81–116.

Se volvió a contar la muestra real aplicando las reglas del programa, sin entrenar:

La pertenencia y el orden recalculados coinciden con splits.json. El filtro y la deduplicación se ejecutan en ese orden. La clave fold(título) conserva puntuación; no agrupa automáticamente títulos parecidos ni todos los documentos del mismo tema. Filtro y particiones: neural.py, 43–50.

La función split_of() toma los primeros ocho caracteres hexadecimales del SHA-256 de esa clave y aplica módulo diez. Es una regla aproximada 80/10/10, no tres porcentajes exactos ni una partición por año. No utiliza la semilla del muestreo. Código: neural.py, 20–22.

n=int(hashlib.sha256(key.encode()).hexdigest()[:8],16)%10
return 'test' if n==0 else ('validation' if n==1 else 'train')

Paso 2: convertir el título a TF-IDF

TF-IDF asigna un valor a cada término del vocabulario: considera cuánto aparece en el título y en cuántos títulos de entrenamiento aparece. Un vector de 4.096 posiciones usa el mismo orden de términos para todos los textos. Una posición cero indica que ese término no aporta señal en esa entrada; no significa que todo el título sea irrelevante.

El proyecto utiliza frecuencia sublineal: para un término presente, tf = 1 + ln(frecuencia). El IDF suavizado es ln((1+n)/(1+df)) + 1, donde n=8750 y df cuenta títulos de entrenamiento que contienen el término. Multiplica ambos valores y normaliza el vector a longitud L2 uno. Las palabras fuera del vocabulario se omiten. Fórmulas de scikit-learn 1.8.

Fragmento literal: fit_transform aprende vocabulario e IDF sólo con entrenamiento; transform aplica esos mismos valores a validación. Código: neural.py, 49–50.

v=TfidfVectorizer(max_features=4096,min_df=2,tokenizer=tokens,token_pattern=None,lowercase=False,sublinear_tf=True,dtype=np.float32)
x=v.fit_transform([d['title'] for d in splits['train']]); xv=v.transform([d['title'] for d in splits['validation']])

Los defaults corresponden a scikit-learn 1.8.0, versión registrada en la construcción. Se distinguieron de los argumentos que el proyecto fija expresamente. Firma de TfidfVectorizer 1.8. En esta auditoría los 4.096 IDF guardados coinciden con el cálculo sobre train dentro de un error máximo de 5,69 × 10⁻⁷, compatible con float32.

Paso 3: transformar, comparar y ajustar los pesos

La red tiene una capa 4096 → 1024 sin sesgo. Es una multiplicación por la matriz W, seguida de normalización L2; no tiene bloques de atención ni arquitectura Transformer. Clase Encoder, neural.py, 16–19.

class Encoder(nn.Module):
    def __init__(self,n:int,dim:int=1024):
        super().__init__();self.linear=nn.Linear(n,dim,bias=False)
    def forward(self,x):return nn.functional.normalize(self.linear(x),p=2,dim=1)

Por cada lote de hasta 96 títulos, el software crea dos máscaras independientes que ocultan cada característica con probabilidad 0,15. No elimina exactamente el 15 % de palabras de cada título. Las dos vistas del mismo título son el par positivo; los otros títulos del lote actúan como negativos, sin que una persona haya juzgado su relación temática.

aa=a*(torch.rand_like(a)>.15); bb=a*(torch.rand_like(a)>.15)
z1=model(aa);z2=model(bb);sim=z1@z2.T/.1; labels=torch.arange(len(a))
return .5*(nn.functional.cross_entropy(sim,labels)+nn.functional.cross_entropy(sim.T,labels))

Este fragmento procede de loss_batch(), líneas 53–58. a tiene hasta 96 filas por 4.096 entradas. z1 y z2 tienen hasta 96 por 1.024. La matriz sim compara cada fila de una vista con todas las de la otra; su diagonal contiene los pares positivos. La temperatura 0.1 escala esas similitudes antes de la pérdida. La entropía cruzada penaliza que otra fila reciba más apoyo que la correspondiente; se calcula en ambos sentidos y se promedia. No es una probabilidad de relevancia de una tesis.

La actualización se ejecuta con esta línea literal. Bucle real: neural.py, 59–66.

a=torch.from_numpy(x[ix].toarray());opt.zero_grad();loss=loss_batch(a);loss.backward();opt.step();losses.append(loss.item())

Su lectura paso a paso: convertir el lote a números para PyTorch; borrar gradientes anteriores; calcular pérdida; backward() calcula cómo influye cada peso en esa pérdida; step() modifica los pesos con AdamW; guardar el valor de pérdida. La red aprende una transformación compartida, no un peso por tesis.

Construcción de AdamW y controles: neural.py, 39–58. Las betas y epsilon son defaults heredados de la versión, no valores seleccionados mediante experimentos de este proyecto. AdamW 2.10. La normalización de salida divide entre el máximo de la norma y 1e-12, epsilon predeterminado de PyTorch; un vector exactamente cero permanece cero. Normalización L2.

La función de cada valor sí está explicada; su optimalidad no está demostrada. No se encontró una búsqueda de hiperparámetros que justificara 4096, 1024, 96 o las tasas como los mejores valores para el corpus. Variarlos es una línea de investigación. La CLI actual no ofrece --dimension, --learning-rate ni --temperature para este encoder: modificar esas constantes exige una versión de código y nuevos artefactos.

Paso 4: validar y conservar una época

Cada época mezcla sólo los 8.750 títulos de entrenamiento. La validación usa 1.144 títulos, sin gradientes, con máscaras reproducibles mediante seed + 77. Se guarda el estado con menor pérdida de validación y se recupera después de completar las cuatro épocas. No se detuvo el entrenamiento en la tercera ni se eligió usando test. Validación y selección: neural.py, 67–87.

La pérdida mide el objetivo contrastivo elegido, no porcentaje de acierto ni satisfacción de usuarios. El código promedia pérdidas de lotes sin ponderarlas por su tamaño. En esta partición hay 92 lotes de train por época —el último de 14 títulos— y 12 de validación —el último de 88—. Cambiar lote o objetivo modifica la interpretación de la pérdida; no se deben comparar esos números como una escala universal de calidad.

encoder.json registra training_seconds=21.916: el intervalo medido comienza antes de preparar la muestra en train() y termina al crear metadatos. No incluye la posterior vectorización de los 593.067 registros, la ingesta PDF ni la entrega completa. Es una lectura histórica de una ejecución, no un benchmark repetido. Se usaron Python 3.11.16, PyTorch 2.10.0+cpu, NumPy 2.3.5 y scikit-learn 1.8.0.

Qué se puede configurar y qué se reutiliza

El kit acepta --train-sample 12000 —límite 20…50.000—, --epochs 4 y --seed 20260909. La función de entrenamiento directo rechaza más de 50.000 registros; por eso el kit entrena una muestra y después codifica el corpus completo. Desde --txt exige --retrain; con --catalog y sin --retrain comprueba y reutiliza los pesos existentes. Opciones: ia_artefactos.py, 491–503; decisión entrenar/reutilizar: 299–333.

La entrega histórica sí entrenó el encoder de títulos. Después se fijó esa transformación para todo el catálogo y los PDF. Las consultas de la página no actualizan sus pesos. Tampoco entrenan Llama.

Volver al índice ↑

Seguir un registro desde el texto hasta su fila numérica

El título real sectesis:000000001, mostrado en la ruta TXT, produce nueve características TF-IDF no nulas. Algunas son causas = 0,345828, evolucion = 0,310049, habitacional = 0,407594 y mexico = 0,158565. El vector tiene 4.096 posiciones; las demás pueden ser cero. Estos valores describen la entrada calculada para ese texto: no son los parámetros aprendidos de la capa lineal.

La siguiente notación explica la operación; no es un nuevo entrenamiento ni una transcripción de una función del repositorio:

x = TF-IDF(título)               # 4096 valores
z = W @ x                       # W: 1024 filas × 4096 columnas
embedding = z / max(||z||₂, ε)   # 1024 valores; ε = 1e-12

@ representa multiplicación de matriz por vector. Cada coordenada de salida combina muchas entradas con diferentes pesos. L2 mide la longitud numérica del vector; normalizar facilita comparar su orientación. Una coordenada no es una palabra o categoría humana identificada.

Primeros seis pesos de la fila 0 de la matriz real W, redondeados:

[0.032730, -0.009829, 0.007284, 0.007827, 0.037297, -0.044680, ...]

Primeros seis valores del vector guardado para sectesis:000000001:

[0.053612, -0.016303, 0.021445, 0.016783, 0.001762, -0.007057, ...]

Primeros seis valores del vector del fragmento PDF …:p33:c0, fila 906 de los vectores PDF:

[-0.003362, 0.006055, 0.056237, 0.017407, -0.037716, 0.040301, ...]

Son extractos numéricos reales, no matrices inventadas ni archivos completos de pesos. En la comprobación guardada como artifacts/ejemplo-encoder-real.json, volver a codificar el título reprodujo el vector almacenado dentro de tolerancia numérica. El ejemplo del PDF pertenece a otro documento: no se afirma una correspondencia automática entre esa tesis y la ficha del TXT.

Pesos, metadatos, IDs y vectores cumplen funciones distintas

El kit conserva por separado training_dataset_sha256, huella de la muestra, y source_sha256, huella del catálogo completo vectorizado. Que esta última identifique 593.067 registros no significa que todos entrenaron la matriz. Procedencia y sellado: ia_artefactos.py, 148–163.

Vectorizar es inferencia con pesos fijos

LocalEncoder reconstruye TF-IDF usando el vocabulario e IDF guardados, carga weights.pt en CPU con weights_only=True y pone la red en modo evaluación. Su método encode() trabaja por lotes de 96 con torch.inference_mode(), sin gradientes ni pasos del optimizador. Fragmento literal del recorrido de inferencia: neural.py, líneas 27–38.

with torch.inference_mode():
    for i in range(0,len(texts),batch_size):
        x=torch.from_numpy(self.vectorizer.transform(texts[i:i+batch_size]).toarray())
        out.append(self.model(x).numpy())

Después de entrenar, train_and_encode() recorre todos los 593.067 títulos y escribe una matriz float32 mediante open_memmap: permite producir un archivo grande por bloques. Cada lote aporta sus filas y sus IDs en el mismo orden; se rechazan números no finitos e IDs duplicados. Construcción de la matriz completa: ia_artefactos.py, 121–147.

Los 6.541 fragmentos PDF pasan por el mismo encoder de títulos con pesos fijos, como documenta training_performed=false de la colección PDF. El texto de entrada ahora es un fragmento; no cambia mágicamente el vocabulario ni añade conocimiento a W. Es una transferencia de representación que requiere evaluar su calidad en ese nuevo tipo de texto. Orquestación de PDF: ia_artefactos.py, 334–347.

Sólo los valores del catálogo ocupan aproximadamente 2,43 GB decimales (593067 × 1024 × 4 bytes), además de la pequeña cabecera NPY. Es tamaño de datos, no RAM adicional medida por consulta ni tamaño de los pesos. La matriz W tiene 4.194.304 parámetros; la matriz de documentos tiene muchísimas más filas porque guarda sus resultados.

Límites visibles de esta representación

El tokenizer conserva como máximo 64 tokens útiles por texto. Un fragmento de 1.600 caracteres puede superar ese límite: la representación densa no necesariamente incorpora todo su contenido. BM25 y la lectura humana sí disponen del texto almacenado del fragmento. Los términos fuera del vocabulario tampoco aportan coordenadas de entrada.

La entrega reporta 7.087 vectores de títulos y 146 de fragmentos PDF con norma inferior a 1e-8, criterio de conteo del kit. Los textos sin señal en el vocabulario pueden producir vectores cero; no deben interpretarse como «tesis sin valor». Permanecen en la colección léxica. Investigar vocabulario, truncamiento y alternativas de encoder puede mejorar cobertura, pero esa mejora todavía debe medirse con consultas y juicios de relevancia.

Volver al índice ↑

Cómo se transforma una pregunta en candidatos densos

La búsqueda densa aplica a la consulta el mismo encoder que creó los vectores de la colección y compara números en el mismo espacio de 1.024 dimensiones. Para dos vectores q y d, el producto escalar suma q[i] × d[i] en todas las coordenadas. Con norma L2 igual a 1, ese producto coincide con la similitud coseno. El modelo normaliza sus salidas; un vector cero conserva norma cero y no aporta una coincidencia densa positiva.

Se usa búsqueda exacta por bloques, sin FAISS, ANN ni GPU. Es una implementación inspeccionable: recorre los vectores elegibles y conserva los mejores. Su coste aumenta con el número de registros y dimensiones; los bloques limitan el trabajo intermedio, pero no eliminan el recorrido. Código: DenseIndex.search y Engine.search.

Al cargar se comprueban hashes, IDs alineados, forma, tipo numérico y valores finitos. La primera búsqueda puede incluir lectura y verificación costosas. La matriz se abre con mmap, pero el catálogo carga sus metadatos en una lista Python y los IDs permanecen en RAM: no todo el buscador funciona sin ocupar memoria. Código: DenseIndex.init y Engine.load_dense.

En catálogo se eligen los registros permitidos por ámbito, años y facultad antes de multiplicar. El siguiente extracto literal muestra el producto y la retención por bloque:

scores = self.vectors[allowed] @ q
for j in np.argsort(-scores, kind='stable')[:k]:
    if scores[j] > 0:
        candidates.append((float(scores[j]), allowed[j]))

Fuente: DenseIndex.search: producto y candidatos. PDF calcula el producto del bloque y enmascara los fragmentos ajenos a doc_id antes de seleccionar resultados. Una consulta sin representación útil puede no recuperar nada en densa y aun así encontrar coincidencias por BM25. Tampoco un coseno alto demuestra que un fragmento responda la pregunta: esa afirmación necesita evaluación.

Cómo se fusionan las dos listas con RRF

La búsqueda híbrida recupera hasta 50 candidatos BM25 y 50 densos dentro de la colección elegida. RRF —fusión recíproca de rangos— suma una contribución por posición; los rangos comienzan en 1:

RRF(documento) = suma, por cada lista donde aparece, de 1 / (60 + rango)

Un documento ausente de una lista no suma por ella. Ejemplo didáctico, no puntuación medida: posiciones 1 y 3 dan 1/61 + 1/63 ≈ 0,032266. Esto permite combinar órdenes sin mezclar directamente BM25 y coseno. Ambas listas tienen el mismo peso; la constante 60 y la profundidad 50 están fijas en los servicios, no en el formulario.

Código literal que evita sumar dos veces un mismo ID en una lista y conserva las señales originales:

for rank,d in enumerate(ranking,1):
    if d['id'] in used:continue
    used.add(d['id']);scores[d['id']]+=1/(constant+rank);docs[d['id']]=d
    signals[d['id']].append({'method':d.get('retrieval_method'),'rank':rank,'score':d.get('score')})

Fuentes: rrf, líneas 49–57, Service.search: profundidad de las listas y Engine.search: fusión PDF. Después se ordenan contribuciones y se devuelven los primeros top_k. En PDF varios fragmentos de una tesis pueden ocupar distintas posiciones: no se aplicó diversificación por documento. Híbrida tampoco busca simultáneamente en TXT y PDF: fusiona dos métodos dentro de la colección seleccionada. La combinación es una técnica implementada; su mejora de relevancia no está demostrada para toda esta entrega.

Qué recibe el servidor y qué recibe Llama

Las rutas de catálogo y PDF aceptan message entre 2 y 2.000 caracteres, method (bm25, dense, hybrid), top_k de 1–50 y generate falso por defecto. El catálogo admite años y facultad; PDF admite doc_id. Rechazan campos desconocidos y cuerpos mayores que 32 KiB. Las consultas de cada colección tienen dos slots simultáneos por proceso; si se ocupan devuelven HTTP 429. Esto es control de concurrencia, no una capacidad multiusuario certificada. Código: Query y BodyLimit, PDFQuery e install y Service: slots y respuesta.

En la web se muestran primero referencias o fragmentos mediante generate:false. Si se selecciona «Redactar con Ollama», después se envía otra solicitud con generate:true; el servidor vuelve a recuperar y prepara contexto. Las fuentes iniciales permanecen visibles durante la espera y se conservan si la redacción falla. Este flujo puede leerse en SectesisRequests.search.

RAG significa generación aumentada con recuperación: pregunta → búsqueda → evidencia → contexto enviado a Llama → respuesta con citas. Para catálogo, se envían metadatos acotados de hasta diez referencias; para PDF, hasta ocho fragmentos y hasta 2.000 caracteres por extracto. La interfaz pide cinco resultados por defecto. No se envían los 593.067 registros ni todas las tesis a cada pregunta. Construcción del contexto: generate del catálogo y generate de PDF.

Llama redacta; el encoder prepara representaciones para buscar. El LLM se reutiliza ya entrenado y no se ajustaron sus pesos con estas tesis. Las preguntas tampoco entrenan automáticamente modelos. El control de citas comprueba marcas como [1] y pertenencia al conjunto disponible, no respaldo semántico de cada afirmación. Al abrir un PDF, la API compara su SHA con el índice y rechaza una versión modificada; esa trazabilidad permite revisar el original, pero no reemplaza la revisión: file: apertura y huella del original.

Variantes para estudiar después

Comparar otro umbral de similitud, profundidad o constante RRF, ponderaciones distintas por método, agrupación por tesis o recuperación de fragmentos vecinos requiere un experimento nuevo. El adaptador index_pretrained permite preparar catálogo con un SentenceTransformer local, revisión y hashes registrados; no se aplicó en estos artefactos. La vectorización PDF actual sólo acepta el encoder didáctico. ANN, rerankers y embeddings de contexto largo son posibles ampliaciones, no componentes ejecutados aquí. Código de la opción existente: index_pretrained: adaptador local de catálogo; restricción PDF: vectorize: modelo admitido.

Volver al índice ↑

Funcionamiento, aprendizaje y calidad son evidencias distintas

El build final utilizó dos consultas derivadas de cada fuente, cada una con hasta cinco de sus primeros tokens útiles. Solicitó tres resultados con generate:false para BM25, densa e híbrida: seis combinaciones colección/método, con dos respuestas en cada una. El reporte registra HTTP 200 y tres citas en cada respuesta, más apertura de un original PDF. La función exige modo extractivo y alguna evidencia por combinación; no compara los resultados contra juicios de relevancia. Se ejecuta mediante ASGI TestClient en el mismo proceso, sin inferencia Ollama. Fuentes: sample_queries: consultas derivadas de fuente y functional_check: comprobación ASGI; resultados en BUILD_REPORT.json dentro de la Release privada.

Evaluador de ranking implementado

evaluate compara recuperación de catálogo con positivos conocidos. Un positivo es un ID que el archivo de casos declara relevante para una pregunta. No evalúa PDF ni generación. Recibe entre 1 y 10.000 casos, verifica IDs existentes en el ámbito y calcula métricas con k=10 por defecto, configurable entre 1 y 50. Un esquema ilustrativo —no un juicio nuevo validado— es:

{
  "id": "pregunta-ejemplo",
  "query": "problema habitacional en México",
  "relevant_ids": ["sectesis:000000001"],
  "human_validated": false
}

Antes de cada medición hace una consulta de calentamiento. Mide después otra llamada secuencial al buscador, sin LLM ni concurrencia. Guarda IDs recuperados, hashes de corpus/casos, métricas por pregunta y promedios. human_validation_declared sólo refleja lo declarado en el JSON; no certifica que una persona revisó las fuentes. Código: evaluate: validación de casos y ejecución; argumentos disponibles: CLI evaluate.

Para leer las fórmulas, k es el máximo de resultados evaluados, H los positivos encontrados entre ellos, P el número total de positivos conocidos y r una posición que comienza en 1:

El evaluador usa relevancia binaria y elimina IDs duplicados antes de tomar k; Precision@k conserva denominador k aunque haya menos resultados. Ejemplo didáctico: con k=5, tres positivos conocidos y dos recuperados en posiciones 2 y 4, Recall es 2/3, Precision 2/5 y MRR 1/2. DCG es 1/log2(3)+1/log2(5); el ideal sitúa los tres positivos en 1, 2 y 3. Este ejemplo explica el cálculo y no es una medición del proyecto. Implementación literal: metrics, líneas 11–18.

hit=sum(i in positive for i in ids)
dcg=sum(1/math.log2(j+2) for j,i in enumerate(ids) if i in positive)
ideal=sum(1/math.log2(j+2) for j in range(min(k,len(positive))))

Para tiempos, el código guarda p50 como elemento central inferior de las latencias ordenadas y p95 como el elemento ceil(0.95 × n) - 1, usando índices desde cero. Esos percentiles describen sus llamadas secuenciales calientes; no representan carga inicial, generación o múltiples usuarios. No calcula intervalos de confianza ni significancia estadística. Fuente: evaluate: resumen y límites.

Qué resultados históricos se pueden citar

El documento VALIDACION.md: comparación proxy histórica registra 100 consultas proxy de títulos conocidos para el laboratorio de 12.000 registros del 10 de septiembre, con otro hash de muestra. Allí figuran Recall@10/MRR@10/nDCG@10: BM25 1,000/0,995/0,996, densa 0,960/0,874/0,895 e híbrida 1,000/0,964/0,973. Es una comparación histórica declarada, no un benchmark nuevo del catálogo de 593.067 ni de los PDF. Sus consultas conservan palabras de títulos y sólo tienen un positivo conocido, por lo que favorecen coincidencias léxicas y no juzgan exhaustivamente otros documentos útiles.

No se encontró en la entrega actual un benchmark humano de relevancia del catálogo completo ni de los fragmentos. Para demostrar mejora, hace falta construir preguntas independientes, revisar positivos y negativos, fijar particiones y criterios antes de comparar variantes, y publicar también errores y limitaciones. El evaluador existente aporta un punto de partida para catálogo; evaluar PDF y respaldo de afirmaciones de Llama necesita ampliar el protocolo y las herramientas.

Las pruebas test_pdf_extension.py crean PDF artificiales y pesos controlados; test_pdf_repository.py usa data/PDF si existe y verifica extracción, BM25, apertura y reutilización. Separar esos tipos de prueba impide presentar un fixture como resultado de las tesis. Código: test_pdf_extension: creación de datos de prueba y test_pdf_repository: integración con data/PDF.

Volver al índice ↑

Llama es el modelo que redacta; Ollama es el programa que lo carga y ejecuta. El buscador entrega unas pocas referencias o pasajes a Llama mediante la API local /api/chat. Los pesos del LLM permanecen fijos durante la consulta. El entrenamiento del encoder de títulos, explicado antes, es un proceso distinto.

Llama 3 es un Transformer autorregresivo: calcula el siguiente token a partir de los anteriores y repite ese paso hasta terminar. La variante Instruct fue preparada por Meta para seguir instrucciones mediante ajuste supervisado y retroalimentación humana; ese trabajo previo no fue realizado por este proyecto. La ficha original describe principalmente uso y evaluación en inglés, por lo que la calidad en español necesita comprobarse con nuestras preguntas. Ficha oficial de Meta Llama 3.

Ficha del modelo realmente instalado

Lectura local del 14 de septiembre de 2026 mediante /api/show y /api/tags, guardada en LLAMA_FICHA_MODELO.json:

El mismo registro local informa la opción heredada num_keep=24 y tres marcas stop: <|start_header_id|>, <|end_header_id|> y <|eot_id|>. Son configuración del paquete; el proyecto no las aprendió ni las cambió. La aplicación tampoco envía num_keep explícitamente. Para un ensayo que altere la ventana o la plantilla, habría que registrar estas opciones heredadas además de las que se envían en cada petición.

Un parámetro aprendido es un número de una matriz o vector del modelo. Por ejemplo, los pesos de atención transforman una representación en consultas, claves y valores; las redes internas combinan características; la salida asigna puntuaciones al vocabulario. No existe una correspondencia «un peso = una tesis»: el conocimiento aprendido está distribuido. Los 8,03 mil millones de Llama tampoco son los 4.194.304 parámetros del encoder local.

Recorrido de una respuesta

1. El sistema recupera evidencia con BM25, vectores o RRF y asigna marcas como [1] y [2].
2. El código construye un mensaje de sistema y un JSON con la pregunta y esa evidencia. Para catálogo incluye metadatos; para PDF incluye pasajes y páginas.
3. Ollama aplica la plantilla de conversación del modelo. El tokenizer convierte el texto en IDs; Llama los transforma en representaciones internas y procesa el contexto.
4. La atención relaciona cada posición con posiciones anteriores. La caché KV conserva claves y valores para evitar recalcular todo el prefijo en cada paso de generación.
5. Llama produce puntuaciones para el siguiente token; la estrategia de decodificación elige uno, lo añade a la secuencia y continúa. Un token puede ser parte de una palabra, un signo o una unidad especial.
6. El servicio recibe el texto y comprueba la sintaxis de las citas. Esa comprobación no demuestra que una afirmación esté respaldada: la persona debe revisar las fuentes.

En forma esquemática: pregunta + evidencia → tokens → representaciones → atención y redes internas → siguiente token → respuesta citada. Una salida fluida no implica comprensión humana, veracidad o lectura de todas las tesis.

Por qué se usa Llama aquí

La razón operativa comprobable es que llama3:latest ya estaba disponible y funcionando en el servidor. Permite mantener la generación local, inspeccionar la configuración y reutilizar la misma API para ensayar otros modelos. Sirve como referencia inicial reproducible y evita introducir una dependencia de una API externa para redactar. No se eligió mediante una comparación que demostrara que es el mejor modelo para bibliotecas o para español.

Para el usuario, su aporte es organizar una explicación breve apoyada en los resultados. Para la investigación, permite separar dos preguntas: «¿recuperamos los pasajes correctos?» y «¿el modelo los usa fielmente?». Entrenar otro LLM desde cero no es un requisito para estudiar esas preguntas; aquí se reutilizan sus pesos y se controla el contexto.

Volver al índice ↑

Los parámetros de ejecución son opciones; cambiarlos no entrena ni modifica los pesos. Esta tabla distingue lo que el código envía de lo que sería una variable experimental:

Las opciones de muestreo se describen en la referencia de parámetros de Ollama; messages, stream y keep_alive, en la API de conversación. No se atribuyen valores predeterminados actuales a una versión antigua del runtime sin medirlos.

Hay dos top_k diferentes: el campo «Resultados» de esta web selecciona referencias del buscador; no cambia options.top_k del modelo. De forma similar, temperature=0 decide cómo generar texto, mientras que la temperatura 0,1 del entrenamiento contrastivo pertenecía a la pérdida del encoder.

Ejemplo reducido de la estructura que prepara el código —las descripciones entre corchetes son marcadores explicativos, no una petición de prueba ejecutada—:

{
  "model": "llama3:latest",
  "stream": false,
  "keep_alive": "15m",
  "options": {"temperature": 0, "num_predict": 500},
  "messages": [
    {"role": "system", "content": "[Instrucciones: español, sólo evidencia y citas]"},
    {"role": "user", "content": "[JSON con pregunta, fragmentos reales y páginas]"}
  ]
}

Cambiar OLLAMA_MODEL seleccionaría otro modelo ya instalado. El formulario actual no expone num_ctx, seed ni muestreo; experimentar con ellos requiere un cliente de laboratorio o una modificación explícita del código. Esta revisión de documentación no cambia esas opciones ni descarga modelos.

Volver al índice ↑

La consulta local observó 8 CPU lógicas y aproximadamente 31,2 GiB de RAM física. Son recursos compartidos: el proceso Ollama vive en el host y el contenedor del buscador tiene su propio límite de 4 CPU y 14 GiB. No debe interpretarse ese límite del contenedor como RAM disponible para Llama. El índice vectorial de catálogo contiene unos 2,43 GB y también compite por memoria y caché del sistema.

La cuantización reduce los bits usados para muchos pesos. Como cálculo orientativo, memoria de pesos ≈ parámetros × bits / 8: 8,03 mil millones a 16 bits serían unos 16,06 GB y a 4 bits unos 4,02 GB, antes de escalas, metadatos, tensores con otra precisión y otros gastos. Por eso Q4_0 no significa que todo el proceso ocupe exactamente cuatro bits por parámetro. En una medición anterior el runtime reportó unos 5,34 GB cargados y 0 bytes de VRAM; se utilizó CPU. En la inspección de metadatos de esta revisión no había un modelo cargado: no se confunde esa lectura con un nuevo ensayo de rendimiento.

La RAM/VRAM necesaria suma pesos, caché KV, buffers y concurrencia. Un contexto mayor consume más memoria; anunciar una ventana larga no prueba que quepa con el resto de la aplicación. La ventana efectiva se debe consultar con el modelo cargado, por ejemplo mediante /api/ps, y no deducirla sólo de la ficha. Contexto en Ollama, modelos cargados y contexto efectivo.

Comparación documental, no benchmark ejecutado

Los tamaños siguientes corresponden a los tags consultados el 14 de septiembre de 2026. Son paquetes en disco, no requisitos certificados de RAM. Los candidatos son una selección manejable para comparar familias y tamaños; no se presentan como los modelos más recientes ni como un ranking universal.

Menos parámetros no garantizan mejor tiempo ni peor calidad. También influyen arquitectura, cuantización, tokenizer, longitud generada, implementación y hardware. Q4_0 y Q4_K_M no son formatos idénticos: una comparación entre esos paquetes evalúa la configuración completa, no aísla sólo la familia. El número de tokens tampoco es directamente comparable entre tokenizers; registrar además longitud de respuesta y tarea resuelta.

Como secuencia de investigación, probar primero Llama 3.2 3B contra la referencia permitiría explorar el intercambio entre consumo y fidelidad; Qwen y Gemma ampliarían la comparación entre familias, y Llama 3.1 ayudaría a estudiar una variante de tamaño cercano. Es una propuesta, no una recomendación basada en resultados locales de esos modelos. Reutilizar la API no garantiza compatibilidad de todas las plantillas ni de las citas sin comprobarlas.

Volver al índice ↑

La evidencia disponible es de llama3:latest en CPU. Dos solicitudes breves consecutivas, con el mismo contexto y el modelo ya cargado, dieron:

Es una medición breve, no una promesa para cualquier consulta. La segunda solicitud puede reutilizar contexto; aquí no se midió una carga inicial en frío. Varios fragmentos largos requieren procesar muchos más tokens. Los límites existentes permiten hasta 400 tokens de salida para catálogo y 500 para PDF; no siempre se llega a esos máximos. Las métricas separan carga, contexto y generación. Métricas de Ollama.

La web anterior cancelaba catálogo a los 65 segundos y PDF a los 90, mientras el servidor permitía 180 segundos a Ollama. La web ahora separa recuperación y redacción: concede 90 segundos a recuperar y 210 a la solicitud de generación, y muestra el tiempo transcurrido. El servidor conserva su timeout de 180 segundos para Ollama y Nginx permite 210. Mostrar fuentes antes reduce la espera para comenzar a leer; no hace que la CPU genere tokens más rápido.

OLLAMA_KEEP_ALIVE=15m permite conservar temporalmente el modelo cargado entre consultas de este servidor. El código mantiene 5m como valor predeterminado para otras instalaciones. Retenerlo reduce recargas, a cambio de ocupar RAM durante más tiempo; no cambia ni entrena el modelo. La opción se transmite a la API local. Parámetro keep_alive de Ollama.

Las duraciones que devuelve Ollama se expresan en nanosegundos. La velocidad de salida se calcula como eval_count / (eval_duration / 1e9); la del contexto usa prompt_eval_count y prompt_eval_duration. El tiempo total observado también puede incluir sobrecarga y espera. La medición anterior de 24,577 s desde el navegador correspondió a otra pregunta de catálogo con una referencia; no se mezcla con estas dos ejecuciones como si fueran el mismo ensayo. Interpretación de las métricas.

No hay tiempos locales medidos para los cuatro candidatos de la tabla. No se inventa una estimación del tipo «un modelo 3B tardará la mitad»: eso es precisamente lo que debe comprobar el experimento.

Volver al índice ↑

Estado: protocolo propuesto; no ejecutado en esta actualización. Las dos mediciones anteriores de Llama sí se ejecutaron; la comparación entre modelos, la evaluación humana y las pruebas de carga siguientes están pendientes. No se descargaron modelos, no se entrenó Llama y no se cambió el modelo del chat.

Preguntas e hipótesis

Los ensayos que descarguen paquetes, retiren el modelo de RAM o generen carga se prepararían en un entorno de laboratorio separado del servicio público. Cambiar la familia de LLM en E1 no necesita reconstruir los índices: se congelan los IDs, el orden y el texto de la evidencia para aislar la redacción. En E2 sí cambia deliberadamente la cantidad de evidencia.

Protocolo reproducible

1. Preparar 30 preguntas reales: 12 respondibles mediante catálogo, 12 mediante pasajes PDF y 6 donde falte evidencia. Un bibliotecario define qué datos o pasajes respaldan cada respuesta y cuándo debería abstenerse el modelo.
2. Reservar 20 para exploración y 10 para evaluación final, con distribución 8/8/4 y 4/4/2 por esos grupos. Guardar la lista y una semilla de partición. No elegir el modelo por el resultado del conjunto final.
3. Registrar commit, hashes de índices/evidencia, digest del modelo, cuantización, plantilla, versión de Ollama, CPU/GPU, RAM/VRAM y opciones efectivas. Para cada condición, mantener estable el resto del sistema.
4. Usar instrucciones equivalentes en español y el mismo contenido de evidencia. Fijar una ventana que acomode pregunta, instrucciones, evidencia y salida en todos los modelos; medir tokens con cada tokenizer y registrar cualquier truncamiento. En la primera comparación se podría ensayar num_ctx=4096, sólo después de comprobar que todos los ejemplos caben.
5. Hacer tres repeticiones por pregunta y condición, alternando el orden de los modelos. Separar carga inicial, contexto nuevo y contexto repetido. Conservar también errores y respuestas truncadas, no sólo las ejecuciones rápidas que salieron bien.
6. Medir tiempo hasta las fuentes, tiempo total de la respuesta, carga, preprocesamiento, generación, tokens de entrada/salida y memoria máxima. Para tiempo al primer token haría falta un cliente con stream=true; la interfaz actual no lo mide.
7. Presentar las respuestas sin identificar el modelo a dos revisores cuando sea posible. Evaluar respaldo de afirmaciones, correspondencia de citas, cobertura, claridad y abstención; resolver desacuerdos y conservar denominadores.
8. Publicar mediana y percentil 95 por condición junto con dispersión y fallos. Con pocos casos el percentil 95 es inestable; no extrapolar a toda la población de usuarios. Comparar calidad y tiempo por la misma pregunta, no sólo promedios de textos diferentes.

Ejemplos para construir preguntas: el registro real sectesis:000000001 permite pedir autor y año; el pasaje de 0609550.pdf, página 33, permite preguntar qué actividades menciona. Pedir resultados o conclusiones ausentes de esos materiales sirve para evaluar abstención. Las respuestas esperadas deben revisarse sobre la fuente completa disponible antes de usarlas como referencia.

Cómo interpretar un resultado

Una cita con formato correcto no basta. Una medida útil es «afirmaciones respaldadas / afirmaciones verificables», acompañada de cobertura de los puntos esperados y abstenciones correctas. Registrar también la proporción de citas que llevan al pasaje que respalda la afirmación. Una mejora de velocidad sería aceptable sólo si cumple criterios de calidad definidos antes del ensayo; los umbrales deben acordarse con quienes usarán el sistema, no inventarse después de ver los resultados.

El entregable del experimento sería una tabla por modelo con tiempo, memoria, respaldo, cobertura y errores, más ejemplos revisados y configuración reproducible. Hoy las casillas de los candidatos se marcarían «pendiente de medir». La ventaja de este proyecto para investigar IA aplicada es que ya separa fuentes, recuperación, representación y generación, lo que permite estudiar cada parte sin atribuir a Llama el trabajo del índice.

Volver al índice ↑

Una API es la interfaz que permite a un programa pedirle una operación a otro mediante mensajes definidos. En este proyecto, el navegador envía JSON a FastAPI; el servidor valida sus campos, consulta la colección elegida y devuelve otro JSON con resultados y procedencia. Esta separación permite probar la recuperación sin abrir la página y estudiar sus parámetros de forma reproducible.

Entrada admitida y valores por defecto

Los modelos Query y BodyLimit y PDFQuery implementan estos controles. El valor inicial de la web está en index.html. Fragmento literal del contrato de catálogo:

class Query(BaseModel):
    model_config=ConfigDict(extra='forbid')
    message:str=Field(min_length=2,max_length=2000)
    method:Literal['bm25','dense','hybrid']='bm25'
    top_k:int=Field(default=5,ge=1,le=50,strict=True)

Ejemplo de petición reproducible a la instalación local sin clave, no una respuesta inventada ni un ensayo nuevo ejecutado al escribir este ejemplo:

curl --fail http://127.0.0.1:8911/api/v1/sectesis/search \
  -H 'Content-Type: application/json' \
  -d '{"message":"problema habitacional México","method":"hybrid","top_k":5,"generate":false}'

Para PDF se usa /api/v1/sectesis/pdf/search, con el mismo núcleo de campos y, opcionalmente, doc_id. La separación de endpoints conserva la distinción entre una ficha bibliográfica y un pasaje del texto. No hay una consulta simultánea de las dos colecciones en ese contrato.

Del envío a las fuentes visibles

1. Validación y acceso. FastAPI valida el JSON. Si la instalación configura una clave, authorize comprueba su Bearer; con clave vacía, como en este servidor público, permite consultar sin ella. Ese mecanismo de acceso no es tokenización lingüística.
2. Capacidad disponible. El catálogo admite hasta dos peticiones simultáneas en su semáforo; PDF tiene otro semáforo de dos. El control cubre recuperación y generación. Si se ocupa, responde 429 con Retry-After: 2; no crea una cola persistente. Son límites del software, no una demostración de cuántos usuarios soportará sin degradarse.
3. Recuperación. El servicio ejecuta el método y los filtros. El índice denso se carga bajo demanda, verifica correspondencia de corpus y vectores y conserva el objeto en memoria. Por eso la primera búsqueda puede incluir trabajo que no aparece en las siguientes.
4. Respuesta extractiva. Devuelve referencias o pasajes aunque no se haya solicitado generación. Cada fuente lleva ID y número de cita; PDF añade página y endpoint del original. El JSON identifica answer_mode, dataset_sha256, retrieved_count, source_status, trace_id y latency_ms.
5. Redacción opcional. Si se pidió, se prepara el contexto acotado de la siguiente subsección. Una falla de generación devuelve advertencia y conserva la respuesta extractiva.

Implementación: authorize y rutas de catálogo, Service.search y Service.answer y ruta PDF search. El UUID trace_id identifica una petición; no demuestra almacenamiento de conversaciones. latency_ms incluye las operaciones del servidor para esa petición, incluida generación cuando procede; no es exclusivamente tiempo de cómputo del modelo.

La web aplica una secuencia adicional: primero envía generate:false, muestra fuentes y sólo después envía generate:true si fue solicitado. Extracto literal de SectesisRequests.search:

const evidence = await post(endpoint, {...body, generate:false}, headers, retrievalTimeout);
onResult(evidence);
if (!body.generate || !evidence.citations.length) return evidence;

La segunda petición vuelve a recuperar en el servidor: no recibe los primeros resultados mediante un identificador de caché. El comportamiento es coherente con artefactos inmutables, pero el programa no compara automáticamente la identidad de las dos listas. El navegador espera hasta 90 segundos en recuperación y 210 en generación, muestra el tiempo transcurrido cada segundo y conserva la primera evidencia si falla la segunda petición. No recibe tokens del LLM uno a uno: el cuerpo enviado a Ollama utiliza stream:false.

Evidencia realmente enviada a Llama

La aplicación no manda toda la base de datos. Selecciona y limita campos antes de preparar el JSON:

Por tanto, pedir 50 resultados no hace que Llama lea 50 referencias. En catálogo no se envían el PDF completo, facultad, grado ni lexical_text en ese contexto. En PDF no se envían imágenes o el archivo binario. Estos recortes controlan longitud por caracteres y por cantidad de fuentes; no calculan el presupuesto exacto de tokens del modelo ni garantizan por sí solos que quepa cualquier contexto.

Extracto literal de generate del catálogo:

context = [{'citation':i, 'title':(d.get('title') or '')[:1500],
            'authors':[str(a)[:150] for a in (d.get('authors') or [])[:5]],'year':d.get('year'),
            'subjects':[str(s)[:200] for s in (d.get('subjects') or [])[:5]]}
           for i,d in enumerate(evidence[:10],1)]

Extracto literal de generate de PDF:

context = [{"citation": c["citation"], "file": c["file"], "page": c["page"], "passage": c["excerpt"][:2000]}
           for c in citations[:8]]

La petición de PDF incorpora esas fuentes y las opciones de ejecución mediante este extracto literal de la misma función:

body = {"model": model, "keep_alive": os.getenv("OLLAMA_KEEP_ALIVE", "5m"), "stream": False, "options": {"temperature": 0, "num_predict": 500},
        "messages": [{"role": "system", "content": system},
                     {"role": "user", "content": json.dumps({"question": question, "evidence": context}, ensure_ascii=False)}]}

Se envían un mensaje de sistema y otro con {question, evidence}. No se envía historial de turnos, aunque la interfaz tenga apariencia de chat. keep_alive conserva temporalmente el modelo cargado; no agrega memoria conversacional a la aplicación. El mensaje de sistema pide español, evidencia y citas y declara que los documentos son datos, no instrucciones. Es una medida de diseño, no una garantía formal contra cualquier respuesta incorrecta o instrucción maliciosa dentro de una fuente.

Qué verifica la respuesta y qué debe revisar una persona

Las funciones limitan la respuesta HTTP a 2.000.000 de bytes acumulados y el texto a 20.000 caracteres. Exigen al menos una marca de cita y que los números correspondan a las fuentes enviadas. Fragmento literal de validación en catálogo:

citations = [int(v) for v in re.findall(r'\[(\d+)\]',text)]
if not citations or any(c<1 or c>len(context) for c in citations):
    return {'ok':False,'error':'Citas ausentes o fuera de la evidencia'}
return {'ok':True,'text':text,'model':model,'citation_check':'syntax_only'}

PDF comprueba pertenencia a sus números de cita con la misma limitación conceptual. Esto no verifica que cada afirmación tenga respaldo, que todas estén citadas, que no se contradigan las fuentes o que se responda bien la pregunta. El modo llm_generated_unreviewed lo identifica como texto sin revisión humana. Una cita sintácticamente válida puede acompañar una afirmación errónea; la comprobación científica requiere contrastar contenido y fuente.

Al abrir el PDF, la ruta files busca un documento indexado, comprueba que la ruta esté dentro del directorio configurado, rechaza enlaces simbólicos y compara SHA-256 del archivo con el índice. Un PDF cambiado devuelve 409 para evitar presentar otra versión como la fuente indexada. El hash prueba correspondencia de bytes, no calidad de extracción o veracidad del contenido.

Volver al índice ↑

El proyecto funciona en https://209.126.127.144/demo/sectesis. El código está en VMOsornio/IA, rama main, dentro de /opt/sites/ia-asistente-virtual/ia-unam. La aplicación se ejecuta en un contenedor; los índices y pesos se prepararon previamente y se montan como archivos persistentes. Consultar no vuelve a entrenar ni a indexar.

Cómo se implementó en este servidor

1. Código y entorno. Se trabajó desde la rama que incorporaba PDF y después se integró la versión validada en main. Se reutilizaron Docker y el Ollama local existente. Dockerfile.final construye un entorno Python 3.11 con las dependencias fijadas del proyecto; WITH_NEURAL=1 incluye el soporte del encoder local.
2. Preparación de datos. Se conservó el catálogo completo de 593.067 registros. Se preparó la selección de 12.000 para el entrenamiento, se filtraron y dividieron los títulos, y 8.750 actualizaron los pesos durante cuatro épocas. Se eligió la tercera por validación y se vectorizó todo el catálogo con esos pesos fijos.
3. Preparación de PDF. Se revisaron 50 originales; la extracción previa produjo 6.541 fragmentos de 49 archivos. El build final reutilizó esas 49 extracciones compatibles, reconstruyó el SQLite BM25 y calculó vectores con el encoder de títulos recién entrenado. La cobertura es parcial en 32 PDF. FAQS1.pdf no produjo texto extraíble. Los PDF y el LLM no se usaron para entrenar otro modelo.
4. Persistencia y contenedores. La entrega preparada quedó en artifacts/entrega-servidor-entrenada-v1/payload. El servicio monta sus archivos como sólo lectura. El contador de visitas usa otra base SQLite en un volumen escribible, sin modificar los índices bibliográficos.
5. Publicación del servicio. Docker Compose ejecuta el buscador y un relay privado hacia Ollama. Nginx recibe HTTPS y reenvía a la aplicación en loopback. El acceso público sin clave fue autorizado por el propietario.
6. Comprobación y traslado. Se comprobaron ambas colecciones con BM25, densa e híbrida, la apertura de un PDF original y la generación real de Ollama por separado. El kit empaquetó índices y pesos en una Release privada, verificó los archivos descargados con SHA-256 y se comprobó una restauración en un directorio nuevo.

Qué hace cada componente

Recorrido de una consulta: navegador → HTTPS/Nginx → API → índice seleccionado → fuentes visibles → Ollama opcional → respuesta. El PDF completo permanece disponible para abrirlo, pero a Llama se envían únicamente los pasajes recuperados y acotados.

La aplicación usa un usuario sin privilegios, raíz de contenedor de sólo lectura y permisos limitados. La configuración local limita el buscador a 4 CPU y 14 GiB; Ollama es otro proceso del host. Los certificados, la configuración particular del servidor y los registros operativos permanecen fuera del repositorio y de la Release. La IP de Docker y el relay deben adaptarse si se instala en otro equipo.

Parámetros de ejecución y separación de recursos

Fuentes versionadas: Dockerfile.final, Compose: variables, montajes y límites y cliente HTTP de generación. Los valores particulares proceden de los archivos locales compose.servidor.local.yml, .env.servidor —sólo variables no secretas revisadas— y operacion-local/ollama_relay.py.

La distinción entre liveness y readiness evita una conclusión equivocada: health devuelve status:'alive' y production_ready:false. El estado del catálogo verifica el manifiesto y muestra dense_loaded; el de PDF comprueba integridad y conteos. Un ready:true no certifica relevancia, funcionamiento del LLM o preparación institucional completa. Es necesario ejecutar las comprobaciones correspondientes a cada capa.

El reporte de artefactos registra además NumPy 2.3.5, scikit-learn 1.8.0, PyMuPDF 1.26.7, FastAPI 0.128.2 y HTTPX 0.28.1. Identifican la ejecución que generó la entrega. Reproducir la misma metodología no implica que cualquier reconstrucción futura tenga bytes idénticos: también deben registrarse commit, versiones, hashes e imagen; un tag como python:3.11-slim puede cambiar con el tiempo.

Visitas, presencia reciente y persistencia

El contador es un componente operativo distinto de la IA. El navegador crea un identificador aleatorio en localStorage y otro por apertura de página. Envía presencia cada 30 segundos mientras está visible; el servidor cuenta como «en línea» las identidades vistas en los últimos 90 segundos. Una recarga puede sumar otra visita. Varias pestañas con el mismo almacenamiento comparten identidad; otro navegador o dispositivo puede contar aparte.

VisitorCounter.record utiliza SQLite con transacción BEGIN IMMEDIATE, hashes de los IDs, un total acumulado, presencia temporal y deduplicación de aperturas durante 86.400 segundos. El cliente visitors.js controla almacenamiento, visibilidad y periodicidad. Fragmento literal del cálculo de presencia:

ONLINE_SECONDS = 90
VIEW_RETENTION_SECONDS = 86400

Por tanto, «personas en línea» es una estimación por navegador y ventana temporal, no personas verificadas o usuarios únicos. Estas tablas no guardan consultas ni IP; tampoco eliminan por sí mismas bots o automatizaciones. Las pruebas de navegador cuentan como aperturas. El volumen ia-unam-servidor_visitors conserva el total entre reinicios; no se mezcla con el SQLite bibliográfico ni con pesos o vectores.

Rutas y variables de esta instalación

En la tabla, las rutas relativas parten de /opt/sites/ia-asistente-virtual/ia-unam. El archivo local .env.servidor contiene las rutas absolutas y tiene permisos 0600.

compose.final.yml aporta la configuración común. Este servidor añade compose.servidor.local.yml para la imagen publicada, los límites y el relay. operacion-local/compose.sh fija el nombre ia-unam-servidor, carga .env.servidor y ambos archivos Compose. Los archivos bajo operacion-local/ son de operación de este host y no se obtienen al clonar.

Valores de generación utilizados aquí: OLLAMA_HOST=http://host.docker.internal:11435, OLLAMA_MODEL=llama3:latest, OLLAMA_TIMEOUT_SECONDS=180 y OLLAMA_KEEP_ALIVE=15m. La primera dirección sólo funciona porque el relay está configurado. SECTESIS_API_TOKEN= vacío corresponde al acceso público de esta instalación; no es una clave que deba compartirse.

Para comprobar y operar este servidor ya instalado, desde su directorio:

cd /opt/sites/ia-asistente-virtual/ia-unam
./operacion-local/compose.sh config --quiet
./operacion-local/compose.sh ps
./operacion-local/compose.sh logs --tail 50 sectesis

Al publicar una imagen previamente construida y validada, se actualiza su referencia local y se aplica con ./operacion-local/compose.sh up -d --no-build --pull never --wait sectesis. Esa operación recrea el servicio cuando cambia la imagen; no reconstruye índices. Un git pull por sí solo actualiza archivos del checkout, pero no sustituye la imagen que ya está ejecutándose.

Cómo el kit convirtió los artefactos en una entrega verificable

El kit es una automatización de los módulos explicados en esta guía. No reemplaza el entrenamiento o los índices con una técnica distinta: invoca sus funciones y ordena preparación, comprobación, empaquetado, publicación y restauración.

El chequeo funcional deriva preguntas de los primeros textos útiles, pide tres resultados y exige alguna evidencia en cada combinación de colección y método. Una de las comprobaciones abre un PDF original y verifica la cabecera %PDF. Sirve para detectar índices rotos o incompatibles; no demuestra que el buscador encuentre lo que necesitan las personas en un conjunto independiente de preguntas. Extracto literal de la petición en functional_check:

responses = [client.post(endpoint, headers=h,
    json={"message": q, "method": method, "top_k": 3, "generate": False}) for q in qs]

Los archivos de reporte tienen momentos y significados diferentes:

Que BUILD_REPORT diga «No Ollama inference» y un reporte posterior pruebe generación no es una contradicción: describen fases distintas. Las pruebas unitarias pueden usar fixtures y transportes simulados para comprobar lógica; no se presentan como los PDF de entrega. Las evidencias locales no se copian indiscriminadamente al Git porque pueden contener información de operación; el manual resume su alcance y mantiene sus nombres para auditoría del propietario.

El artefacto de datos procede del commit 9193ce88f586783d3d8ab5dd93ec6880f49116a9; la revisión de código citada en este manual es 01bbc0ccb4d79ff5b829420e0d67f032827c099b. Las mejoras posteriores de documentación/interfaz no equivalen a un nuevo entrenamiento. Esa separación permite actualizar la aplicación y seguir utilizando una entrega de datos identificada por hashes.

Cómo instalar una copia en otro equipo

Se necesita Git, GitHub CLI autenticado con acceso al repositorio privado, Python 3.11 o posterior para restaurar y Docker con Compose para ejecutar. Los comandos siguientes se usan en un directorio nuevo del equipo de destino; no se vuelven a clonar encima de la instalación existente. La construcción puede descargar dependencias de software, pero la restauración no descarga modelos ni entrena.

gh auth status
gh repo clone VMOsornio/IA IA-unam -- --branch main --single-branch
cd IA-unam
gh release download ia-unam-artifacts-20260914-0428 --repo VMOsornio/IA --dir artifacts/descarga-artefactos
python3 artifacts/descarga-artefactos/ia_artefactos.py restore --assets artifacts/descarga-artefactos --out artifacts/restaurados-v1

Los destinos de descarga y restauración deben ser nuevos. El paquete contiene 20 partes, 2.660.066.142 bytes comprimidos y 4.760.857.985 bytes restaurados. El restaurador comprueba SHA-256 de las partes y de los archivos. Antes de extraer exige espacio libre para el tamaño expandido más 15 % de margen y una copia temporal del comprimido; también ocupa espacio la descarga ya existente. La Release conserva el commit con el que se prepararon sus datos; main contiene la interfaz actualizada compatible. No incluye el TXT bruto ni el modelo de Ollama. Los 50 PDF originales ya versionados bajo data/PDF se obtienen con el clone; no se añadieron originales nuevos a la Release. Debe conservarse ese montaje para abrir las fuentes, además de restaurar sus datos derivados. El payload tiene 19 archivos; las 20 partes son segmentos del archivo comprimido, no 20 modelos o 20 datasets distintos.

Crear un archivo .env.servidor nuevo sustituyendo /ruta/IA-unam por la ruta absoluta real de esa copia:

SECTESIS_ARTIFACTS=/ruta/IA-unam/artifacts/restaurados-v1/sectesis
SECTESIS_PDF_ARTIFACTS=/ruta/IA-unam/artifacts/restaurados-v1/pdf
SECTESIS_PDF_INPUT_DIR=/ruta/IA-unam/data/PDF
SECTESIS_PDF_VECTORS=/ruta/IA-unam/artifacts/restaurados-v1/pdf-vectors
SECTESIS_PDF_DENSE_DIR=/pdf_vectors
SECTESIS_PORT=8911
WITH_NEURAL=1
SECTESIS_API_TOKEN=
OLLAMA_MODEL=
OLLAMA_TIMEOUT_SECONDS=180
OLLAMA_KEEP_ALIVE=15m

Con OLLAMA_MODEL vacío se puede probar la recuperación sin redacción. Para añadir generación, configurar un Ollama local con un modelo ya disponible y una dirección accesible desde el contenedor. En Linux, un servicio ligado sólo a 127.0.0.1 del host no se vuelve accesible automáticamente mediante host.docker.internal; hace falta una conexión privada adecuada, como el relay de la instalación descrita. Las capacidades del modelo y sus plantillas deben comprobarse antes de usar otro paquete.

chmod 600 .env.servidor
docker compose -p ia-unam --env-file .env.servidor -f compose.final.yml config --quiet
docker compose -p ia-unam --env-file .env.servidor -f compose.final.yml build sectesis
docker compose -p ia-unam --env-file .env.servidor -f compose.final.yml up -d --wait sectesis

La copia queda disponible localmente en http://127.0.0.1:8911/demo/sectesis. El valor vacío de SECTESIS_API_TOKEN deja las consultas sin clave en ese acceso local; una instalación privada puede establecer una clave propia. Publicar en Internet requiere configurar el proxy HTTPS y el acceso del nuevo servidor; clonar no instala sus certificados ni copia automáticamente la infraestructura del servidor de origen.

Comprobaciones iniciales para esa configuración local sin clave:

curl --fail http://127.0.0.1:8911/health
curl --fail http://127.0.0.1:8911/api/v1/sectesis/status
curl --fail http://127.0.0.1:8911/api/v1/sectesis/pdf/status
curl --fail http://127.0.0.1:8911/api/v1/sectesis/visitors

Después, realizar consultas en ambas colecciones con los tres métodos, revisar fragmentos y abrir un PDF. /health sólo comprueba que el proceso responde, no la relevancia de las respuestas ni el estado completo de los datos. Para una instalación con clave, las rutas de API necesitan su autorización correspondiente. Los contadores se conservan en el volumen del proyecto Compose; no eliminarlo con down -v si se quieren mantener las visitas. No agregar bases, índices, pesos o archivos de configuración privada al historial Git.

Volver al índice ↑

El resultado es un laboratorio funcional de IA aplicada a datos de bibliotecas y tesis, con una interfaz pública y un proceso reproducible. Permite observar cómo los datos se convierten en índices, cómo un encoder aprende una representación y cómo un LLM utiliza evidencia recuperada para redactar.

Aportes disponibles y utilidad

Qué se desarrolló y qué se logró

Se desarrollaron el parser bibliográfico, la normalización a JSONL, los índices SQLite FTS5, el entrenamiento y la inferencia del encoder, la extracción y fragmentación PDF, la recuperación léxica/densa/híbrida, la API y la interfaz con fuentes. Se integró generación local mediante Ollama, validación sintáctica de citas, publicación y restauración de artefactos, contenedores y contadores persistentes.

La entrega logró hacer consultable el catálogo completo de este TXT y los fragmentos extraídos de los PDF disponibles. El encoder tiene 1.024 dimensiones y se entrenó durante cuatro épocas con la partición de títulos indicada; todos los títulos del catálogo y los fragmentos PDF se representaron después con pesos fijos. El servicio ya permite consultar, comparar métodos y abrir fuentes. Las comprobaciones de API, navegador, integridad, persistencia y generación confirman ese funcionamiento; no son una medición humana de exactitud o utilidad institucional.

Qué se aprendió y qué conocimiento se practicó

El aprendizaje técnico documentado se expresa en decisiones y resultados que pueden revisarse en el código:

Estos conocimientos se pueden revisar en el código, la configuración y los ejemplos. El laboratorio permite recorrer el proceso completo y detectar dónde se origina un resultado: extracción, segmentación, índice, representación, recuperación o generación.

Alcance del proyecto y valor del laboratorio

El alcance actual incluye consulta de fichas y pasajes, comparación de recuperación, redacción opcional con fuentes y despliegue reproducible. No abarca todo el acervo UNAM, todos los procesos de gestión bibliotecaria, lectura visual de páginas, OCR general, entrenamiento de un LLM propio ni respuestas cuya exactitud haya sido garantizada. Tampoco une automáticamente cada ficha del catálogo con un PDF ni consulta ambas colecciones a la vez.

Su utilidad como laboratorio es ofrecer una base real para aprender, demostrar y experimentar: un estudiante puede seguir la transformación de los datos; un desarrollador puede reproducir el servicio; una persona usuaria puede buscar y comprobar fuentes; y un bibliotecario puede ayudar a evaluar si los resultados responden a necesidades reales. Es una base para investigar mejoras y no una afirmación de que la IA sustituye el criterio bibliotecario.

El conocimiento central adquirido en el proceso es que aplicar IA exige organizar los datos, definir qué se recupera, controlar qué recibe el modelo y comprobar el resultado. Una representación aprendida o una respuesta bien escrita sólo aporta valor cuando se entiende su procedencia y sus límites. Los experimentos de la sección anterior permiten estudiar ese valor sin confundir funcionamiento técnico con calidad demostrada.

Código de consulta: search.py, dense.py, service.py, app/pdf_rag/engine.py y ambos generation.py. Evidencia local: BUILD_REPORT.json, registros de verificación por HTTPS y navegador, OLLAMA_DIAGNOSTICO_TIEMPOS.json, EJEMPLOS_PROCESO_REAL.json, EJEMPLO_FRAGMENTOS_CONSECUTIVOS.json y ejemplo-encoder-real.json. Consultar el glosario completo.

Volver al índice ↑

Esta sección es un programa de investigación, no una descripción de trabajo ya realizado. Los valores empleados constituyen una configuración reproducible del laboratorio. No se encontró una comparación controlada que demuestre que 1.600 caracteres, 1.024 dimensiones, temperatura contrastiva 0,1 o cuatro épocas sean óptimos para estas tesis. Explicar la función de un parámetro justifica su papel técnico; demostrar que su valor es el mejor exige ensayos.

Opciones existentes que aún no tienen resultados en esta entrega

El repositorio incluye index_pretrained: permite crear un índice de catálogo con un SentenceTransformer ya disponible localmente, identificando modelo, revisión y archivos. Usa CPU, local_files_only=True, trust_remote_code=False, lotes de codificación de 8 y un máximo de secuencia de hasta 512 tokens, limitado además por el propio modelo. Puede usar semantic_text y un prefijo de consulta. Esa ruta no se activó aquí. Tampoco es un reemplazo directo para todo el sistema: la vectorización PDF y el kit de esta entrega esperan el encoder didáctico. Aplicarla a PDF o empaquetarla requiere adaptar y probar esas rutas. Código: index_pretrained, líneas 78–110, comprobación del modelo PDF.

También se puede cambiar el método de consulta, top_k, los filtros o activar/desactivar la redacción sin entrenar. Cambiar el texto usado por el encoder, su vocabulario o sus pesos exige calcular vectores compatibles de nuevo. Cambiar la fragmentación cambia las unidades de recuperación: obliga a reconstruir el índice PDF y sus vectores en una versión nueva, y revisar los juicios de relevancia cuyos IDs dependían de los fragmentos anteriores.

Hipótesis por etapa

Los valores alternativos de la tabla son candidatos ilustrativos para diseñar un ensayo, no una recomendación validada ni comandos que se hayan ejecutado.

El OCR propuesto puede investigarse mediante Page.get_textpage_ocr, una capacidad de PyMuPDF que requiere Tesseract; el código actual llama a extracción de texto y no a ese método. Referencia oficial de OCR.

Faiss ofrece familias de búsqueda exacta y aproximada con distintos compromisos de memoria, coste y recuperación. Aquí no está integrado; una eventual incorporación debe compararse con los productos escalares exactos del proyecto y respetar los filtros antes de devolver resultados. Documentación oficial de Faiss.

Un cross-encoder calcula una puntuación procesando consulta y candidato juntos; puede estudiarse como segunda etapa para pocos candidatos, con coste adicional por pareja. No se aplicó en esta instalación. Documentación oficial de Sentence Transformers.

Protocolo común para no confundir cambios con mejoras

1. Formular una pregunta y una hipótesis antes de ejecutar: por ejemplo, si otro corte recupera más pasajes relevantes sin superar un límite de tiempo acordado.
2. Fijar datos y procedencia: commit, hashes, versión del parser, fragmentos, encoder, dependencias y recursos. Separar conjunto de desarrollo y prueba; agrupar preguntas del mismo documento cuando corresponda para evitar contaminación entre grupos.
3. Preparar juicios de relevancia revisados, con criterios explícitos y desacuerdos registrados. Para PDF, anotar documento/página y evidencia; si cambian los fragmentos, revisar su correspondencia. Incluir preguntas sin evidencia en un protocolo separado: el evaluador actual requiere al menos un positivo por caso.
4. Cambiar una variable por ensayo inicial y mantener las demás comparables. Cuando se estudien interacciones, declarar un diseño factorial; no atribuir un resultado a una sola variable si cambiaron varias.
5. Registrar cada ejecución, errores incluidos. Para latencia, distinguir arranque/carga diferida de consultas con datos ya cargados, alternar el orden de los métodos y repetir. El calentamiento de una búsqueda puede beneficiar a la siguiente.
6. Comparar relevancia, coste y fallos por pregunta; informar tamaño del conjunto, dispersión y ejemplos de regresión. Si se estiman intervalos mediante remuestreo, documentar la unidad de muestreo y el procedimiento. No existe en esta entrega un cálculo automático de significación estadística.
7. Elegir configuraciones con desarrollo/validación; consultar test cuando estén fijadas. Conservar el sistema anterior para contrastar, y publicar la conclusión junto con sus límites y los archivos reproducibles.

El resultado científico posible es una respuesta acotada a una pregunta, con evidencia verificable. Puede mostrar una mejora, un empate o que una técnica añade coste sin beneficio; los tres resultados son informativos. Los experimentos de Llama descritos antes complementan estas pruebas de recuperación y preparación, sin convertirlas en entrenamiento del LLM.

Volver al índice ↑

Las referencias siguientes fijan el commit auditado 01bbc0c. Los nombres de funciones permiten localizar la acción; los archivos de salida permiten comprobar qué produjo. La configuración y los manifiestos determinan qué ruta se utilizó realmente.

Para repetir una inspección local sin imprimir el corpus completo, desde la raíz del repositorio:

# Leer las funciones auditadas y la configuración común.
sed -n '39,91p' app/sectesis_ai/neural.py
sed -n '49,67p' app/pdf_rag/ingest.py
sed -n '170,205p' app/pdf_rag/engine.py
cat compose.final.yml
# Leer reportes de esta instalación; adaptar la ruta en una copia restaurada.
python3 -m json.tool artifacts/entrega-servidor-entrenada-v1/payload/BUILD_REPORT.json
python3 -m json.tool artifacts/entrega-servidor-entrenada-v1/BUILD_STATUS.json
python3 -m json.tool artifacts/entrega-servidor-entrenada-v1/UPLOAD_RESULT.json

Los reportes del kit describen una entrega, no se actualizan con cada visita ni con cada cambio de documentación. La imagen en ejecución, el commit de la interfaz y el commit de preparación de datos pueden ser distintos; deben registrarse por separado. Las dependencias fijadas están en requirements-final.txt y requirements-final-ml.txt. La reproducibilidad numérica también depende de plataforma y versiones: una semilla sola no promete identidad bit a bit en cualquier equipo.

Volver al índice ↑