Diseño de Artie, un asistente de documentación de IA
Lee la publicación complementaria del blog para obtener un contexto más amplio: Lo que me enseñó crear un asistente de documentación con IA sobre la redacción técnica. En ella se analiza la generación aumentada por recuperación y cómo encaja este proyecto en la redacción técnica.
Este caso de estudio repasa las decisiones de diseño que hay detrás de Artie, un asistente de documentación de IA creado con Algolia e integrado en este sitio de documentación. Artie es un asistente de generación aumentada por recuperación (RAG) que responde solo a partir del contenido publicado aquí. Su prompt de sistema mantiene las consultas de documentación ancladas a ese contenido en lugar de a conocimientos generales de entrenamiento. La restricción reduce las alucinaciones y evita características inventadas.
Crear un asistente de documentación parece sencillo hasta que se tienen en cuenta los casos extremos: ¿qué ocurre cuando alguien formula una pregunta que la documentación no cubre? ¿Y si dos públicos distintos utilizan la misma interfaz? ¿Cómo se le da personalidad a una IA sin dejar que divague? ¿Y cómo se evita que alguien secuestre por completo el prompt?
Esta página explica cómo este diseño resuelve cada uno de esos problemas.
Enrutamiento de públicos
Artie atiende a dos públicos a través de una sola interfaz conversacional:
- Desarrolladores y usuarios finales que buscan instrucciones de configuración, referencias de API o explicaciones sobre las muestras de documentación
- Reclutadores y directores de contratación que evalúan este portafolio y pueden preguntar sobre cualificaciones, experiencia o el proceso de redacción
En lugar de crear flujos separados o pedir a los usuarios que se identifiquen, el prompt enruta según la intención. Las preguntas técnicas reciben respuestas paso a paso basadas en el índice de documentación. Las preguntas relacionadas con el portafolio reciben respuestas que sintetizan el contexto del currículum con las muestras de redacción del sitio. Si el contexto del currículum no está disponible en el índice, Artie redirige a los visitantes a la página «Acerca de mí» en lugar de intentar generar una respuesta.
La interfaz ofrece a ambos públicos un solo chat sin menús, y cada uno recibe una respuesta relevante.
Base de conocimiento y recuperación de información
La restricción más importante en el diseño de Artie es que responde exclusivamente a partir del índice de documentación impulsado por Algolia. Este es el principio fundamental de la generación aumentada por recuperación. Las respuestas del modelo se basan en un conjunto específico de contenidos, en lugar de partir de datos de entrenamiento generales.
- Sin contenido inventado significa que el asistente nunca inventa características ni crea enlaces de descarga, y solo describe pasos que aparecen en la documentación.
- Enlaces a la fuente significa que el asistente proporciona URL o referencias a archivos del índice para que los usuarios abran directamente la página correspondiente.
- Respuesta alternativa elegante significa que Artie expone la limitación con claridad cuando el índice carece de información relevante y luego sugiere ponerse en contacto directamente, sin reintentar ni especular.
Artie no puede ayudar con nada que quede fuera de la documentación publicada. En un sitio de portafolio, esa restricción ayuda: la precisión importa más que la amplitud. Una respuesta precisa y bien documentada a una pregunta concreta genera más confianza que una respuesta que suene plausible pero que resulte ser errónea.
Calibración de la personalidad y el tono
Artie tiene una personalidad ligera basada en una calidez tranquila, inspirada en George Harrison, con algún que otro toque del dialecto de Liverpool. La palabra clave es ligera. La personalidad añade carácter a los saludos y las despedidas sin interferir en el contenido técnico.
Las restricciones de diseño aquí son intencionadas:
- Mantener las respuestas técnicas concisas significa que la personalidad nunca justifica respuestas más largas. Un saludo cálido seguido de una respuesta concisa y objetiva logra este objetivo.
- Variedad frente a repetición significa que el prompt incluye un repertorio de expresiones para que Artie evite recurrir siempre a la misma frase.
- Sin sermones significa que el personaje mantiene un tono cálido e irónico y nunca suena prepotente, actuando como un colega servicial en lugar de una interpretación teatral.
Este tipo de ajuste del tono es un reto habitual en el diseño de IA conversacional. Demasiada personalidad hace que el asistente parezca un truco publicitario. Muy poca lo hace parecer robótico. La solución es tratar la personalidad como un condimento: presente, pero nunca como el ingrediente principal.
Seguridad y medidas de protección
Un asistente de IA dirigido al público constituye una superficie de ataque, y el prompt incluye defensas explícitas contra las vulnerabilidades habituales de los modelos de lenguaje grande (LLM).
Protección contra la inyección de prompts
El prompt de Artie rechaza explícitamente cualquier intento de anular sus instrucciones, como comandos del tipo «ignora las instrucciones anteriores» o solicitudes para adoptar una personalidad diferente. Esto establece defensas a nivel de prompt contra la inyección de prompts, clasificada en el puesto #1 del Top 10 de OWASP (Open Worldwide Application Security Project) para aplicaciones de modelos de lenguaje grande.
Restricción del alcance
El prompt define categorías de rechazo explícitas:
- El asistente rechaza las solicitudes de ayuda general de programación que no cubre la documentación.
- El asistente rechaza las solicitudes de curiosidades no relacionadas, salvo dos funciones lúdicas delimitadas.
- El asistente rechaza las consultas sobre información personal que el portafolio profesional no publica.
- El asistente remite a los visitantes directamente para tarifas freelance o negociaciones.
Cada categoría tiene un límite claro, así que el asistente no sopesa qué está "suficientemente cerca" para responder. Si una solicitud cruza ese límite, la declina educadamente.
Privacidad de datos
Artie solo comparte información de contacto que esté explícitamente publicada en la documentación, como un perfil de LinkedIn o el correo del portafolio. No adivinará, inferirá ni generará detalles personales como números de teléfono o direcciones.
Límites profesionales
El asistente no interactuará con mensajes hostiles, no usará lenguaje vulgar ni se saldrá de su personaje. Esto va más allá de la cortesía. Se trata de mantener un comportamiento predecible. Un reclutador que ponga a prueba los límites del asistente se topará siempre con un límite coherente y profesional.
Easter eggs controlados
Artie incluye dos "funciones divertidas", los datos curiosos de Snapple Real Facts y los chistes inofensivos, que muestran cómo añadir personalidad sin abrir la puerta a abusos.
Ambas funciones comparten el mismo patrón de diseño:
- Desencadenantes explícitos significan que las funciones se activan solo cuando el usuario las pide («dame un dato de Snapple», «cuéntame un chiste») y nunca ante indicaciones vagas.
- Contenido delimitado significa que los datos de Snapple se anclan a una lista integrada de datos verificados, mientras que los chistes permanecen seleccionados y aptos para toda la familia.
- Sin invención infundada significa que el asistente evita inventar datos o generar humor ajeno a la marca, de modo que la salida sigue siendo predecible.
Las funciones creativas ilimitadas consumen tokens a toda velocidad y producen resultados impredecibles. El contenido seleccionado y los desencadenantes explícitos aportan calidez sin ese riesgo.
Lo que haría de otra manera
Los usuarios reales cambiaron este diseño.
- Coste de tokens motiva el primer cambio. La lista de datos de Snapple supera los 100 elementos por sí sola. En un sistema de producción con facturación por token, trasladaría eso a una capa de recuperación en lugar de integrarlo en el prompt del sistema. Un equipo paga por cada token del prompt en cada solicitud, tanto si el usuario pide un dato como si no.
- Contexto multiturno limita el diseño actual a preguntas y respuestas de un solo turno. Una versión posterior podría mantener el historial de conversación y reescribir las consultas para resolver preguntas de seguimiento como «¿Y qué hay del siguiente paso?».
- Analítica y retroalimentación siguen sin implementarse. Registrar solo los recuentos de respuestas de contingencia revelaría qué lagunas de documentación producen más fallos.
- Ajuste dinámico de personalidad exige editar hoy las expresiones codificadas. Trasladarlas a una configuración externa facilitaría los cambios de tono sin tocar el conjunto de instrucciones principal.
Cada uno de estos aspectos es una concesión deliberada para un proyecto de portafolio en el que la simplicidad y la claridad importan más que la optimización a escala de producción. Pero son las primeras cosas que abordaría si esto pasara a un entorno con mayor tráfico.