Tutorial de IA de Haystack: Construir flujos de trabajo agenéticos

Durante la era de la Generación Recuperada-Aumentada (RAG), marcos como LangChain se hicieron populares para desarrollar aplicaciones de IA. Sin embargo, a medida que el mundo se desplaza hacia los flujos de trabajo de la IA Agenética, los marcos como Haystack AI están adquiriendo protagonismo debido a su flexibilidad, modularidad y eficacia en el manejo de una amplia gama de casos de uso.

En este tutorial, conoceremos Haystack AI, exploraremos sus componentes clave y casos de uso, y aprenderemos a construir un flujo de trabajo de IA agéntica que integre múltiples herramientas. Un flujo de trabajo agéntico se refiere a sistemas en los que los modelos lingüísticos invocan de forma autónoma herramientas y componentes basados en consultas del usuario para alcanzar un objetivo.

Si eres nuevo en el tema, asegúrate de consultar nuestros tutoriales sobre IA Agenética y RAG Agenética.

Mantenemos a nuestros lectores al día de lo último en IA enviándoles The Median, nuestro boletín gratuito de los viernes que desglosa las noticias clave de la semana. Suscríbete y mantente alerta en sólo unos minutos a la semana:

¿Qué es la IA de Haystack?

Pajar es un marco de trabajo de código abierto diseñado para crear aplicaciones altamente personalizables y listas para la producción, basadas en grandes modelos lingüísticos (LLM). Permite a los programadores crear una amplia gama de sistemas impulsados por la IA, incluidos pipelines RAG, flujos de trabajo basados en agentes, sistemas de búsqueda de última generación e incluso aplicaciones de IA totalmente autónomas.

La arquitectura modular de Haystack permite a los programadores integrar las principales tecnologías y herramientas de IA, como OpenAI, Hugging Face Transformers, Chroma, herramientas MCP, Elasticsearch, etc. 

Es más sencillo que Langchain y ofrece un amplio arreglo de herramientas para crear tus componentes y agentes con sólo unas pocas líneas de código.

En esencia, Haystack se estructura en torno a componentes y canalizaciones, que trabajan conjuntamente con proveedores de LLM, almacenes de documentos, herramientas, agentes y un rico ecosistema de integraciones. Estos bloques proporcionan a los programadores la capacidad de diseñar, personalizar y desplegar sistemas de IA de extremo a extremo.

Fuente: Visión general de los Conceptos Haystack

Componentes clave de Haystack

Utilizando los siguientes componentes de Haystack, puedes construir robustos flujos de trabajo RAGo incluso combinar ambos para aplicaciones avanzadas de IA.

1. Componentes

Haystack ofrece varios componentes para tareas específicas como la recuperación, la generación o el almacenamiento de documentos. Estos componentes son clases de Python con métodos invocables que se inicializan con parámetros y se ejecutan mediante el método run(). 

La API de componentes agiliza el proceso de creación de componentes personalizados, incluidos los de API y bases de datos de terceros. 

2. Generadores

Los generadores se encargan de producir respuestas textuales basadas en las indicaciones que reciben. En el backend, estos generadores aprovechan las API proporcionadas por los proveedores de LLM y se adaptan para satisfacer requisitos específicos.

Hay dos tipos de generadores:

1. Generadores de chat: Están diseñados para contextos conversacionales y permiten completar el chat interactuando con una serie de mensajes.

2. Generadores no chat: Se utilizan para tareas de generación de texto más sencillas, como la traducción o el resumen.

3. Recuperadores

Recupera documentos relevantes de un almacén de documentos en función de las consultas del usuario. Este sistema está personalizado para almacenes de documentos específicos, lo que les permite gestionar requisitos de base de datos únicos con parámetros personalizados. Por ejemplo, el almacén de documentos de Elasticsearch dispone de paquetes tanto de recuperador como de almacén de documentos.

4. Almacenes de documentos

La interfaz de almacenamiento de documentos de Haystack gestiona eficazmente los documentos. Incluye funciones como write_documents () y delete_documents () para gestionar los datos. Los componentes pueden interactuar fácilmente con el Almacén de Documentos para leer o escribir documentos. Se puede utilizar un componente DocumentWriter para escribir datos en Almacenes de Documentos para flujos de trabajo más complejos.

5. Clases de datos

Las clases de datos simplifican la comunicación entre componentes de forma sencilla y modular. La información se intercambia dentro del sistema como entradas o salidas en conductos.

Hay dos tipos de clases de datos:

• Clase de documento: Esta clase incluye texto, metadatos, tablas o datos binarios. Los documentos pueden almacenarse en Almacenes de Documentos o transferirse entre componentes.
• Clase de respuesta: Esta clase contiene la respuesta generada, la consulta original y los metadatos relacionados.

6. Tuberías

Los pipelines combinan componentes, almacenes de documentos e integraciones en flujos de trabajo personalizables. Admiten funciones como flujos simultáneos, componentes independientes, bucles, así como pasos de preprocesamiento, indexación y consulta. Los pipelines pueden guardarse en formatos como YAML o TOML para reutilizarlos o compartirlos.

7. Agentes

Los agentes de IA son sistemas autónomos que utilizan grandes modelos lingüísticos para tomar decisiones y abordar tareas complejas. Puedes crear herramientas para conectar con una API, dárselas al agente y luego hacerle una pregunta. El agente analizará la consulta y utilizará las herramientas adecuadas en función de tu pregunta.

Empieza con Haystack AI

En esta sección, aplicaremos los componentes clave de Haystack para construir un flujo de trabajo Agentic AI que se utilizará con la herramienta RAG y de acceso web, según la consulta del usuario. 

1. Configurar el entorno

Para esta guía, utilizaremos DataLab como entorno de codificación. Para empezar, instalaremos los siguientes paquetes de Python: Haystack, OpenAI, Tavil e itertools. He aquí para qué se utiliza cada paquete:

1. Pajar: Para crear pipelines y agentes para construir aplicaciones basadas en LLM.
2. Tavil: Para acceder a la funcionalidad de búsqueda web mediante API.
3. OpenAI: Para utilizar LLMs y modelos de incrustación.
4. itertools: Para herramientas avanzadas de iteración y bucle eficiente en Python.

!pip install -qU \
    "haystack-ai[agentst]" \
    tavily-python \
    openai \
    more_itertools

Para utilizar OpenAI y Tavily, establece sus claves API como variables de entorno. Si utilizas DataLab, puedes añadir variables de entorno accediendo a la pestaña Entorno y seleccionando la opción Variables de entorno.

También puedes programarlos en Python:

import os

os.environ["OPENAI_API_KEY"]  = "sk-..."   # ← paste your OpenAI key
os.environ["TAVILY_API_KEY"]  = "tvly-..." # ← paste your Tavily key

2. Preparar la base de conocimientos

Crearemos una base de conocimientos utilizando la clase de datos Documento de Haystack. Esta base de conocimientos contendrá información sobre la ciudad de Islamabad.

from haystack.dataclasses import Document
from typing import List, Any, Dict


docs: List[Document] = [
    Document(content="Islamabad experiences a humid subtropical climate with hot summers and mild winters."),
    Document(content="Peak tourist season in Islamabad is during spring (March to May) and autumn (September to November) due to pleasant weather."),
    Document(content="Faisal Mosque, one of the largest mosques in the world, is an iconic landmark in Islamabad designed by Turkish architect Vedat Dalokay."),
    Document(content="Islamabad was purpose-built as the capital of Pakistan in the 1960s, designed by Greek architect Constantinos Apostolos Doxiadis."),
    Document(content="The city is known for its well-planned infrastructure, wide roads, and green spaces, making it one of the most organized cities in Pakistan."),
]

3. Construir el canal de almacenamiento de documentos

El almacén de documentos actúa como un almacén vectorial, almacenando incrustaciones de texto y permitiendo una recuperación eficaz basada en las consultas del usuario. 

Aquí lo haremos:

1. Crea un almacén de documentos en memoria.
2. Construye un canal Haystack con componentes como un incrustador OpenAI y un escritor de documentos.
3. Convierte los documentos en incrustaciones y guárdalos en un almacén de documentos.

from haystack.document_stores.in_memory import InMemoryDocumentStore
from haystack.components.embedders import OpenAIDocumentEmbedder
from haystack.components.writers import DocumentWriter
from haystack import Pipeline, component

document_store = InMemoryDocumentStore(embedding_similarity_function="cosine")

indexing_pipeline = Pipeline()
indexing_pipeline.add_component("embedder", OpenAIDocumentEmbedder(model="text-embedding-3-small"))
indexing_pipeline.add_component("writer", DocumentWriter(document_store=document_store))
indexing_pipeline.connect("embedder", "writer")

indexing_pipeline.run({"embedder": {"documents": docs}})

Después de ejecutar el pipeline, los documentos se almacenan correctamente como incrustaciones:

Calculating embeddings: 1it [00:00,  1.34it/s]


{'embedder': {'meta': {'model': 'text-embedding-3-small',
   'usage': {'prompt_tokens': 128, 'total_tokens': 128}}},
 'writer': {'documents_written': 5}}

4. Crear la Herramienta GAR

Una vez rellenado el almacén de documentos, crearemos una herramienta de búsqueda RAG personalizada. 

Esta herramienta lo hará:

1. Convierte las consultas de los usuarios en incrustaciones.
2. Realiza búsquedas de similitud en el almacén de documentos.
3. Recupera los documentos pertinentes.

from haystack.tools import ComponentTool
from haystack.components.embedders import OpenAIDocumentEmbedder, OpenAITextEmbedder
from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever

@component()
class RagSearcher:
    """Query ‑> top‑k docs from the private store"""
    def __init__(self, document_store, top_k: int = 3):
        self.text_embedder = OpenAITextEmbedder(model="text-embedding-3-small")
        self.retriever = InMemoryEmbeddingRetriever(document_store=document_store, top_k=top_k)

    @component.output_types(documents=List[Document])
    def run(self, text: str) -> Dict[str, Any]:
        emb_out = self.text_embedder.run(text=text)
        docs_out = self.retriever.run(query_embedding=emb_out["embedding"])
        return {"documents": docs_out["documents"]}

rag_tool = ComponentTool(
    component=RagSearcher(document_store),
    name="rag_search",
    description="Semantic search over the Islamabad knowledge base."
)

5. Crear una herramienta de búsqueda web

Como Tavily no tiene componentes nativos de Haystack, crearemos una herramienta de búsqueda web personalizada utilizando la API de Tavily. Esta herramienta obtendrá resultados de búsquedas web en directo y los devolverá como objetos Document.

import os
import requests
from haystack import component
from haystack.dataclasses import Document
from typing import List

@component
class TavilyWebSearch:
    def __init__(self, api_key: str, top_k: int = 3):
        self.api_key = api_key
        self.top_k   = top_k

    def run(self, query: str):
        resp = requests.post(
            "https://api.tavily.com/search",
            json={
                "api_key": self.api_key,
                "query": query,
                "max_results": self.top_k,
                "include_answer": True,
            },
            timeout=15,
        )
        resp.raise_for_status()
        data = resp.json()

        docs: List[Document] = []
        if answer := data.get("answer"):
            docs.append(Document(content=answer, meta={"source": "tavily:direct_answer"}))

        for hit in data.get("results", []):
            docs.append(
                Document(
                    content=hit["content"],
                    meta={
                        "title": hit["title"],
                        "url": hit["url"],
                    },
                )
            )
        return {"documents": docs}


web_tool = ComponentTool(
    component=TavilyWebSearch(api_key=os.environ["TAVILY_API_KEY"], top_k=3),
    name="web_search",
    description="Live web search via Tavily ."
)

6. Construir un agente

Crearemos un generador utilizando las funciones OpenAI y el último modelo gpt-4.1-mini. En primer lugar, desarrollaremos el indicador del sistema que ayudará al Agente a determinar qué herramientas debe utilizar para las peticiones concretas de los usuarios. Por último, crearemos el Agente con el generador, el indicador del sistema y una lista de herramientas.

Según la indicación del sistema, el Agente comprobará primero la información utilizando la búsqueda RAG. Si la pregunta del usuario se refiere a las últimas noticias, el tiempo o las noticias de última hora, el Agente utilizará directamente la herramienta de búsqueda web.

from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.components.agents import Agent

generator = OpenAIChatGenerator(model="gpt-4.1-mini")

system_prompt = """
You are a helpful assistant.
- Use rag_search first to retrieve information from the knowledge base.
- Use web_search only when the query requires fresh, real-time, or external information (e.g., weather, breaking news).
"""

agent = Agent(
    chat_generator=generator,
    system_prompt=system_prompt,
    tools=[rag_tool, web_tool],
)

7. Probar la herramienta RAG

Haremos una pregunta sobre Islamabad para invocar la herramienta GAR para responder.

from haystack.dataclasses import ChatMessage

msg = ChatMessage.from_user("What is the peak tourist season in Islamabad?")
resp = agent.run(messages=[msg])
print(resp["messages"][-1].text)

Tenemos respuestas con un alto grado de conciencia contextual, pero ¿cómo sabemos que ha utilizado las herramientas GAR para responder?

The peak tourist season in Islamabad is during spring (March to May) and autumn (September to November).

8. Analizar las herramientas utilizadas

Para comprobar qué herramientas se invocan, crearemos una función que extraiga información sobre las herramientas.

def tools_used(run_output: dict) -> list[str]:
    seen, ordered = set(), []

    for msg in run_output["messages"]:
        for call in msg.tool_calls:
            if call.tool_name not in seen:
                ordered.append(call.tool_name)
                seen.add(call.tool_name)
    return ordered
print("Tools invoked →", tools_used(resp))

En la primera prueba, el agente sólo utilizó la herramientarag_search para responder a la pregunta.

Tools invoked → ['rag_search']

9. Probar la herramienta web

Ahora preguntaremos por el tiempo en Islamabad. En lugar de invocar la herramienta GAR, utilizará la herramienta de búsqueda web para responder a la pregunta.

msg = ChatMessage.from_user("What is the temperature in Islamabad now?")
resp = agent.run(messages=[msg])
print(resp["messages"][-1].text)
print("Tools invoked →", tools_used(resp))

La respuesta es muy precisa, y ha utilizado la herramienta de búsqueda web para responder a la pregunta.

The current temperature in Islamabad is 31°C with a real-feel temperature of 32°C.
Tools invoked → ['web_search']

Si tienes problemas para ejecutar el código anterior, consulta el Cuaderno Datalab: Tutorial Haystack AI - DataLab.

Casos de uso de Haystack

Hemos cubierto los aspectos básicos del marco de la IA de Haystack. El siguiente paso en tu viaje de aprendizaje es crear una aplicación de IA totalmente funcional. Éstos son algunos de los casos de uso que están explorando los programadores:

1. IA multimodal: Desarrollar sistemas que procesen e integren diversos tipos de entrada, incluidos texto e imágenes, para aplicaciones como el subtitulado de imágenes, la transcripción de audio y la generación de imágenes.
2. IA conversacional: Proporcionar interfaces de chat para chatbots dinámicos de varios turnos que puedan entablar conversaciones significativas.
3. Tuberías agénticas: Utiliza la llamada funcional para que los modelos lingüísticos puedan interactuar con herramientas y acceder a capacidades externas.
4. RAG avanzado: Combina la recuperación de documentos con la generación basada en LLM para aplicar diversas estrategias de recuperación y generación.
5. Integración de herramientas MCP: Conecta sin problemas los LLM con herramientas externas, API y fuentes de datos utilizando el Protocolo de Contexto del Modelo.
6. Evaluación del modelo: Evalúa la precisión, pertinencia y fiabilidad de las canalizaciones.
7. Aplicaciones multiagente: Crea sistemas en los que varios agentes colaboren eficazmente para resolver tareas complejas de varios pasos.

Reflexiones finales

Tras haber trabajado con muchos marcos LLM, Haystack me parece una de las opciones más intuitivas y flexibles que existen. Su uso es más natural, menos complejo y ofrece un mayor control sobre tus flujos de trabajo. 

Una de sus características más destacadas es la facilidad con la que puedes crear componentes personalizados para tus canalizaciones, lo que lo hace muy adaptable a una amplia gama de casos de uso.

Disfruté especialmente experimentando con agentes y herramientas y comprendiendo cómo invocar cada uno de ellos eficazmente. Trabajar con el indicador del sistema me ayudó a comprender cómo utilizar las herramientas individualmente y en secuencia. 

Además, el aviso del sistema se puede personalizar fácilmente para incluir detalles adicionales, como mostrar las fuentes y los ID de los documentos, que pueden ser importantes para tu aplicación.

Si eres nuevo en el mundo de los agentes de IA, consulta los siguientes recursos para obtener más información: 

• Comprender a los agentes de IA 
• Tipos de agentes de IA 
• Marcos de agentes de IA 
• Tutorial RAG Agentic con Proyecto Demo
• Guía N8n con ejemplos prácticos