Heretic: ablación direccional automatizada para modelos de lenguaje

Todo lo que hay que saber sobre p-e-w/heretic: una aplicación de línea de comandos que modifica modelos Transformer mediante ablación direccional y optimización automática.

Qué es Heretic

Heretic es una herramienta de Python para modificar modelos de lenguaje basados en Transformer sin un ciclo de ajuste posterior costoso. Su caso de uso principal declarado es reducir las negativas de respuesta mediante una variante parametrizada de ablación direccional, a la que el proyecto llama también abliteration.

El proyecto no presenta esa modificación como una mejora de seguridad ni como una garantía de conservación de capacidades. Busca un compromiso medido entre menos negativas y menor divergencia KL frente al modelo original; el propio README advierte que los valores dependen de plataforma y hardware y que las métricas automáticas no sustituyen la evaluación humana.

$Ilustración dramática que representa la tensión entre supresión de negativas y preservación de capacidades: una red neuronal brillante dividida por la mitad por una línea de fractura luminosa. En un lado, estructuras cristalinas oscuras y dentadas que representan negativas se desmoronan y disuelven en partículas; en el otro, flujos de datos prístinos en cian y dorado permanecen intactos, representando capacidades preservadas del modelo, con una balanza de luz neón perfectamente equilibrada entre ambas fuerzas.$

La distribución publicada en PyPI se llama heretic-llm y expone el ejecutable heretic; PyPI mostraba la versión 1.4.0 durante esta consulta.

El origen: de investigación independiente a herramienta automatizada

El autor y mantenedor identificado por el repositorio es Philipp Emanuel Weidmann (p-e-w). Su perfil se describe como matemático e ingeniero de software con quince años de experiencia industrial e investigador independiente en alineamiento e interpretabilidad de modelos de lenguaje.

La cita incluida por el propio proyecto atribuye Heretic a Weidmann y lo fecha en 2025. En lugar de pedir que el usuario ajuste manualmente capas y pesos, el diseño automatiza la búsqueda de parámetros con Optuna; esa elección responde a la tensión central del proyecto: intervenir sobre direcciones de negativa sin degradar innecesariamente la conducta del modelo fuera de esas pruebas.

El proyecto se apoya explícitamente en el trabajo de Arditi y colaboradores de 2024, en textos de Jim Lai y en observaciones publicadas por Maxime Labonne. El README insiste en que Heretic fue escrito desde cero y no reutiliza código de las implementaciones anteriores que enumera.

Filosofía y principios

Automatización antes que ajuste manual: al iniciar una ejecución, el programa determina el tamaño de lote, calcula direcciones y explora parámetros; no exige conocer internamente la arquitectura Transformer.

Conservar una señal de calidad: la selección de ensayos combina el recuento de negativas con la divergencia KL respecto del modelo de partida, en vez de optimizar únicamente la supresión de negativas.
Trazabilidad de distribución: el sitio oficial ofrece PyPI, GitHub, un espejo oficial en Codeberg, archivos de publicación, Internet Archive e IPFS; explica esa redundancia como una medida de resiliencia ante interrupciones.
Verificación de la cadena de suministro: el proyecto declara versiones bloqueadas con uv, demora de siete días para actualizaciones de dependencias, firmas Sigstore de publicaciones y firmas GPG de los commits del mantenedor.

Cómo funciona

Heretic calcula, para cada capa, vectores residuales de la primera ficha de salida a partir de conjuntos de indicaciones clasificados como benignos y perjudiciales. Trata la diferencia de medias como una dirección de negativa y ortogonaliza matrices de proyección de atención y de la capa MLP respecto de esas direcciones.

El optimizador TPE de Optuna busca combinaciones de direction_index y de pesos de ablación por componente. Según el README, permite interpolar linealmente índices de dirección no enteros y aplicar pesos distintos a atención y MLP; el motivo técnico declarado es que las intervenciones MLP tienden a ser más dañinas que las de atención.

El recorrido documentado es: detección de GPU, carga y análisis del modelo desde Hugging Face, carga de indicaciones, determinación del lote máximo, detección opcional de prefijos de razonamiento, evaluación inicial, cálculo de direcciones, ensayos de optimización y elección en el frente de Pareto. Al final el programa ofrece guardar, subir a Hugging Face, conversar con el resultado o ejecutar evaluaciones.

Además incluye funciones de interpretabilidad: --plot-residuals crea proyecciones PaCMAP en PNG y una animación GIF; --print-residual-geometry imprime métricas cuantitativas de la geometría residual. PaCMAP se ejecuta en CPU y la documentación avisa que en modelos grandes puede tardar una hora o más.

Estado oficial y semioficial

Heretic es un proyecto independiente: no se recuperó evidencia de aceptación en un mercado oficial de un proveedor de modelos ni de respaldo formal por parte de Hugging Face, PyTorch, Google, Qwen u otro fabricante. Sí cuenta con un sitio de documentación propio, paquete en PyPI, repositorio público, enlace oficial a Hugging Face, Discord, Matrix y un espejo oficial de Codeberg.

En la práctica, su distribución por PyPI y sus publicaciones firmadas facilitan una instalación verificable, pero no equivalen a certificación de resultados, seguridad de los modelos modificados ni aprobación de los proveedores de modelos.

El ecosistema

Repositorios y canales del proyecto

p-e-w/heretic es el repositorio principal. El perfil público del autor también destaca p-e-w/waidrin, p-e-w/sorcery y p-e-w/arrows, pero las páginas recuperadas no demuestran que sean dependencias, extensiones o componentes de Heretic; por tanto se registran solo como proyectos del mismo autor.
El sitio oficial enlaza un espejo oficial en Codeberg, el perfil de Hugging Face, Discord y Matrix. Esos canales son parte de la infraestructura de publicación y comunidad, no repositorios derivados.
El repositorio incluye configuraciones predefinidas: config.default.toml para supresión de negativas, config.noslop.toml para supresión de slop y config.nohumor.toml para supresión de humor.

Antecedentes, bifurcaciones y extensiones relacionadas

El README nombra como implementaciones públicas previas de técnicas de ablación a AutoAbliteration, abliterator.py, wassname’s Abliterator, ErisForge, Removing refusals with HF Transformers y deccp. Esta lista acredita relación temática, no compatibilidad, mantenimiento activo, equivalencia funcional ni una comparación independiente de calidad.

La búsqueda de bifurcaciones, repositorios con el mismo nombre y puertos localizados no pudo completarse mediante la API de GitHub: durante esta ejecución devolvió límite de tasa. La página pública sí muestra aproximadamente 3.000 bifurcaciones, pero no se atribuyen puertos, traducciones o extensiones concretas sin poder verificar su README o descripción.

Números del repositorio

Medición: 13 de agosto de 2026, páginas públicas de GitHub; la API REST estaba limitada por tasa.

Métrica	Valor visible
Estrellas	27,4 mil
Bifurcaciones	3 mil
Commits	192
Ramas	8
Etiquetas	5
Incidencias abiertas	42
Solicitudes de cambios abiertas	31
Versión más reciente	`v1.4.0`, publicada el 14 de junio de 2026
Licencia	AGPL-3.0 o posterior
Lenguaje y entorno declarado	Python; consola y GPU

Las cifras abreviadas se conservan tal como las muestra GitHub; no se convierten en enteros exactos. La página de publicaciones lista v1.4.0 como la última y muestra a ricyoung, anrp, p-e-w, kabachuha, coder3101, zaakirio, MoonRide303, UnstableLlama, umran666, Vinay-Umrethe, rocker-zhang e iuyua9 entre quienes participaron en esa publicación, pero no se pudo recuperar un ranking global de contribuidores sin API.

GitHub separa visualmente las 42 incidencias abiertas de las 31 solicitudes de cambios abiertas. Como la API no estuvo disponible, no se informa subscribers_count, que es distinto del campo watchers_count duplicado por GitHub, ni un total de incidencias mezclado con solicitudes de cambios.

Cómo contribuir

No se recuperó un archivo CONTRIBUTING.md ni una política de contribución separada en la raíz visible del repositorio. El README establece, no obstante, que al contribuir se acepta publicar la aportación bajo la misma AGPL-3.0 o posterior.

Hay evidencia de un proceso de cambios activo: el repositorio contiene tests/, flujos de GitHub Actions y una publicación v1.4.0 que lista aportaciones de doce participantes; la página de código muestra además pruebas de extremo a extremo y una publicación reciente de cambios de dependencias. La sección de discusiones también está habilitada y muestra categorías de anuncios, general, ideas, encuestas, preguntas y respuestas, y demostraciones. Eso no permite inferir una plantilla de solicitud de cambios, requisitos de rama o comandos de prueba no documentados.

Cómo lo recibió la comunidad

La evidencia comunitaria recuperable es desigual y debe leerse con cautela:

El README reúne tres testimonios externos enlazados sobre modelos producidos con Heretic: una persona que empezó escéptica valora la calidad de respuestas extensas de un modelo GPT-OSS 20B; otra lo considera el mejor modelo no restringido que había probado; y otra informa que un Qwen3-4B modificado era el mejor que podía ejecutar con 16 GB de VRAM. Son experiencias seleccionadas por el propio proyecto, no una reseña independiente ni un benchmark reproducido aquí.
La incidencia 401, abierta por Weidmann el 5 de julio de 2026, comunica que prevé poder dejar de desarrollar software en un futuro indeterminado. El colaborador rocker-zhang respondió que trabajar en Heretic había sido un placer y agradeció su trabajo; accemlcc, identificado por GitHub como colaborador, escribió que el proyecto había significado mucho para él y que había aprendido de él. Son reacciones personales al anuncio, no una evaluación técnica.
En la lista pública de incidencias aparecen problemas concretos: luyangliu616 abrió la incidencia 345 diciendo que no consiguió hacerlo funcionar, y sefgtrdh abrió la 318 por la ausencia de libcaffe2_nvrtc.so. Estas incidencias muestran fricción real de instalación y compatibilidad, no prueban que los problemas afecten a todos los entornos.
No se recuperó un hilo directo verificable de Hacker News: la página de envíos por dominio quedó vacía y la consulta de Algolia no devolvió registros utilizables. Reddit devolvió un desafío de acceso. Por ello no se inventan identificadores, puntos, comentarios, opiniones de X, videos, lanzamiento en Product Hunt ni menciones en podcasts. Tampoco se obtuvieron descargas de PyPI porque el servicio de estadísticas respondió con límite de tasa.

Heretic frente a otras propuestas

Propuesta	Coincidencia verificable	Límite de la comparación
AutoAbliteration	El README la enumera como implementación pública de ablación.	No se recuperó su documentación en esta ejecución; no se afirman diferencias de algoritmo ni rendimiento.
`abliterator.py`	Figura en los antecedentes públicos enumerados por Heretic.	La fuente solo demuestra la relación temática.
wassname’s Abliterator	Figura en la lista de implementaciones previas.	No se recuperaron su README ni métricas; no se puede afirmar compatibilidad.
ErisForge	Figura como implementación pública anterior.	No hay base recuperada para comparar flujo, licencia o resultados.

La distinción verificable de Heretic está en combinar ablación direccional parametrizada con una búsqueda TPE que cooptimiza negativas y divergencia KL, además de presentar un flujo de consola automatizado. Cualquier afirmación de que supera a las propuestas enumeradas requeriría recuperar y reproducir sus métodos y evaluaciones, algo que no se hizo en esta investigación.

Guía rápida de uso

Instalación y primer arranque

Prepare un entorno de Python 3.10 o posterior y tenga instalado PyTorch 2.2 o posterior adecuado para su GPU; PyTorch debe instalarse manualmente porque el comando depende del acelerador. Algunos modelos, como los cuantizados MXFP4, requieren PyTorch 2.6 por torch.accelerator.
Instale la versión estable:

pip install -U heretic-llm

Interfaz de terminal en modo oscuro brillando en una pantalla negra, mostrando la palabra heretic en verde neón brillante en el prompt de comando, con líneas en cascada de registros de ejecución de Python desplazándose debajo en texto cian monoespaciado. La ventana de terminal flota en un entorno cyberpunk oscuro con partículas de datos holográficas sutiles a la deriva en el fondo.

Ejecute el programa con el identificador de un modelo de Hugging Face:

heretic Qwen/Qwen3-4B-Instruct-2507

En la documentación actual también aparece Qwen/Qwen3.5-4B como ejemplo. En el primer arranque se detecta la GPU, se descarga el modelo si no está en caché, se calcula un tamaño de lote y se solicitan decisiones al terminar la optimización.

Para reproducibilidad de dependencias, quien clone el repositorio puede utilizar:

uv run heretic

El proyecto incluye uv.lock para fijar las versiones utilizadas por los desarrolladores.

Flujos de trabajo habituales

Modificar un modelo y guardar o publicar el resultado: ejecute heretic <id-del-modelo>. Tras la optimización, la interfaz ofrece guardar el modelo, subirlo a Hugging Face, abrir un chat de prueba o ejecutar evaluaciones.
Evaluar un modelo generado: use el patrón documentado heretic --model google/gemma-3-12b-it --evaluate-model p-e-w/gemma-3-12b-it-heretic. Los valores pueden cambiar con el hardware y el entorno.
Reducir uso de VRAM: configure quantization con bnb_4bit. La documentación señala que la carga de cuatro bits mediante bitsandbytes puede reducir aproximadamente un 70 % de VRAM.
Explorar representaciones internas: instale el extra y ejecute el indicador correspondiente:

pip install -U 'heretic-llm[research]'
heretic --plot-residuals
heretic --print-residual-geometry

El primero genera imágenes y una animación; el segundo imprime métricas de geometría residual.

Configuración esencial

config.toml: archivo de configuración habitual; se coloca en el directorio de trabajo desde el que se ejecuta Heretic.
config.default.toml: plantilla para la supresión de negativas; cópiela o renómbrela como config.toml antes de ajustarla.
quantization: seleccione bnb_4bit para cargar con cuantización de cuatro bits y disminuir la VRAM necesaria.
n_trials: controla la cantidad de ensayos de optimización; el tutorial muestra 200 ensayos como ejemplo, no como requisito universal.
good_prompts, bad_prompts, good_evaluation_prompts y bad_evaluation_prompts: determinan los conjuntos de indicaciones usados para calcular direcciones y evaluar el compromiso entre negativas y divergencia.

Los parámetros también pueden pasarse por línea de comandos, consultables con heretic --help, o mediante variables de entorno con el patrón HERETIC_<NOMBRE_DEL_PARÁMETRO_EN_MAYÚSCULAS>.

Trampas frecuentes y soluciones

Versión de PyTorch insuficiente: PyTorch 2.2 es el mínimo, pero MXFP4 y gpt-oss necesitan características de PyTorch 2.6. Instale la variante apropiada de PyTorch para su acelerador antes de instalar o ejecutar Heretic.
Memoria insuficiente: active quantization = "bnb_4bit"; el tutorial la propone para reducir VRAM. Mantenga la determinación automática de lote salvo que deba imponer un límite con max_batch_size.
Expectativa de ejecución corta: el tutorial ilustra una optimización de 200 ensayos que dura algo menos de tres horas en su ejemplo; planifique el tiempo y no trate ese valor como garantía para otro modelo o GPU.
Fallo de biblioteca CUDA observado por un usuario: la incidencia 318 menciona libcaffe2_nvrtc.so ausente. La documentación no publica una corrección específica; la acción fundamentada es revisar que PyTorch, el controlador y la biblioteca de aceleración correspondan al hardware antes de abrir una incidencia con datos del entorno.
Instalación desde fuentes no verificadas: las publicaciones oficiales incluyen firmas Sigstore; use los archivos de firma de la publicación y siga el procedimiento de verificación del sitio si instala un archivo comprimido.

Integraciones y migración

Heretic consume identificadores y modelos de Hugging Face y, al terminar, ofrece subir el resultado al mismo ecosistema. Su integración práctica principal es ese flujo de modelo → modificación → guardado, chat, evaluación o publicación; no se recuperó documentación de integración con MCP, editores, CI o plataformas de mensajería.

Para instalación resiliente, el proyecto documenta PyPI, clonación por GitHub o Codeberg y archivos de publicación disponibles también mediante Internet Archive e IPFS. No se recuperó una guía de migración desde AutoAbliteration, Abliterator u otra herramienta; no se debe asumir compatibilidad de configuraciones o pesos entre ellas.

Casos de uso

Investigadores de interpretabilidad que necesiten inspeccionar direcciones residuales pueden usar --plot-residuals y --print-residual-geometry para generar proyecciones, animaciones y métricas, con la salvedad de que PaCMAP puede ser costoso en CPU.
Personas con un modelo Transformer compatible y una GPU que quieran aplicar un procedimiento de ablación sin elegir manualmente una capa o unos pesos pueden usar la detección de lote, el cálculo de direcciones y la optimización TPE incorporados.
Equipos que distribuyen modelos derivados en Hugging Face pueden aprovechar la salida de guardado, conversación, evaluación y publicación que ofrece el flujo final. Deberán validar el resultado en su dominio: el proyecto declara que los benchmarks automáticos no reemplazan la evaluación humana.
Quienes operan en entornos con restricciones de conectividad o preocupación por procedencia pueden elegir entre PyPI, GitHub, Codeberg, archivos firmados, Internet Archive e IPFS, y verificar las firmas Sigstore de las publicaciones.

Recursos

Repositorio: https://github.com/p-e-w/heretic
Documentación oficial: https://heretic-project.org/
Tutorial y primer arranque: https://heretic-project.org/tutorial
Instalación y archivos firmados: https://heretic-project.org/installation
Configuración: https://heretic-project.org/configuration
Seguridad y verificación: https://heretic-project.org/security
Paquete de PyPI: https://pypi.org/project/heretic-llm/
Publicaciones: https://github.com/p-e-w/heretic/releases
Comunidad: Discord y Matrix enlazados desde https://heretic-project.org/
Conversaciones e incidencias: https://github.com/p-e-w/heretic/discussions, https://github.com/p-e-w/heretic/issues, https://github.com/p-e-w/heretic/issues/401

Nota: este artículo combina documentación oficial, páginas públicas de GitHub y PyPI consultadas el 13 de agosto de 2026. Las cifras cambian con el tiempo; la API de GitHub y las estadísticas de PyPI estaban limitadas por tasa durante esta investigación.