LangChain Salida Estructurada

La mayoría de las veces, no necesitas un texto libre, sino datos estructurados, como objetos JSON.

La salida estructurada (Structured Output) de LangChain permite que el Agent devuelva resultados según el formato que especifiques, para que el programa pueda usarlos directamente.


¿Por qué necesitamos salida estructurada?

Supongamos que necesitas extraer nombre, edad y profesión de una descripción del usuario:

MétodoFormato de salidaProcesamiento posterior
Respuesta normal"Zhang San tiene 28 años y es ingeniero"Se necesitan expresiones regulares o volver a llamar al modelo para parsear
Salida estructurada{name: "Zhang San", age: 28, job: "Ingeniero"}Se utiliza directamente como objeto de Python

La salida estructurada elimina el paso de "parsear datos desde el texto", permitiendo que la salida de la IA se use directamente en el programa.


El uso más simple: pasar un modelo Pydantic

Solo pasa el modelo Pydantic al parámetro response_format:

Ejemplo

from dotenv import load_dotenv
load_dotenv()

from pydantic import BaseModel, Field
from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
from langchain.messages import HumanMessage


# Definir la estructura de salida esperada
class CourseInfo(BaseModel):
    """Resultado de extracción del curso de EJEMPLO Tutorial para Principiantes"""
    course_name: str = Field(description="Nombre del curso")
    difficulty: str = Field(description="Dificultad: Principiante/Intermedio/Avanzado")
    estimated_hours: int = Field(description="Duración estimada de estudio (horas)")
    is_free: bool = Field(description="Si es gratuito")


model = init_chat_model("deepseek:deepseek-v4-flash", temperature=0)
agent = create_agent(
    model=model,
    response_format=CourseInfo,  # Pasar el modelo Pydantic
    system_prompt="Eres el asistente de cursos de EJEMPLO Tutorial para Principiantes, extrae la información del curso de la descripción del usuario.",
)

# El usuario ingresa una descripción no estructurada
result = agent.invoke({
    "messages": [HumanMessage(
        content="Recientemente estoy estudiando el tutorial básico de Python3, es de nivel principiante,"
                "se necesitan unas 20 horas de estudio, y es completamente gratuito"
    )]
})

# Obtener el resultado estructurado desde structured_response
if "structured_response" in result:
    course = result["structured_response"]
    print(f"Nombre del curso: {course.course_name}")
    print(f"Dificultad: {course.difficulty}")
    print(f"Duración estimada: {course.estimated_hours} horas")
    print(f"Gratuito: {'Sí' if course.is_free else 'No'}")
    print(f"Tipo de objeto: {type(course)}")

Resultado de ejecución:

Nombre del curso: Python3 基础教程
Dificultad: 入门
Duración: 20 小时
Gratis: 是
Tipo de objeto: <class '__main__.CourseInfo'>

El structured_response devuelto es una instancia del modelo Pydantic, no un diccionario común. Esto significa que puedes acceder mediante atributos como .course_name, y el IDE también ofrece autocompletado.


Salida Estructurada que coexiste con herramientas

response_format y tools se pueden usar al mismo tiempo: el Agent llama a las herramientas cuando es necesario y finalmente genera datos estructurados:

Ejemplo

from pydantic import BaseModel, Field
from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
from langchain.messages import HumanMessage
from langchain.tools import tool


@tool
def search_course(keyword: str) -> str:
    """Buscar información de cursos en EJEMPLO Tutorial para Principiantes"""
    courses = {
        "python": "Tutorial básico de Python3 | Principiante | Gratuito | 30 capítulos | Aprox. 20 horas",
        "java": "Tutorial básico de Java | Principiante | Gratuito | 35 capítulos | Aprox. 25 horas",
        "Análisis de datos": "Análisis de datos con Python | Intermedio | Membresía | 25 capítulos | Aprox. 30 horas",
    }
    return courses.get(keyword.lower(), f"No se encontraron cursos relacionados con '{keyword}'")


class CourseRecommendation(BaseModel):
    """Resultado de recomendación del curso"""
    course_name: str = Field(description="Nombre del curso recomendado")
    reason: str = Field(description="Motivo de la recomendación")
    difficulty: str = Field(description="Dificultad: Principiante/Intermedio/Avanzado")


model = init_chat_model("deepseek:deepseek-v4-flash", temperature=0)
agent = create_agent(
    model=model,
    tools=[search_course],
    response_format=CourseRecommendation,
    system_prompt="Eres el asesor de cursos de EJEMPLO Tutorial para Principiantes. Primero consulta los cursos y luego haz recomendaciones.",
)

result = agent.invoke({
    "messages": [HumanMessage(content="Quiero aprender Python, ¿qué me recomiendas?")]
})

rec = result["structured_response"]
print(f"Curso recomendado: {rec.course_name}")
print(f"Motivo de la recomendación: {rec.reason}")
print(f"Dificultad: {rec.difficulty}")

# Ver el proceso completo
print("\n"=== Proceso de ejecución ===")
for msg in result["messages"]:
    if msg.type == "tool":
        print(f" Llamando a {msg.name}: {msg.content}")

Resultado de ejecución:

Curso recomendado: Python3 基础教程
Razón: 该课程免费且适合Python初学者,学习时长约20小时
Dificultad: 入门

=== 执行过程 ===
  调用 search_course: Python3 基础教程 | 入门 | 免费 | 30章 | 约20小时

Estructuras anidadas complejas

Pydantic admite estructuras complejas como anidamiento, listas, enumeraciones, etc.:

Ejemplo

from pydantic import BaseModel, Field
from typing import Literal
from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
from langchain.messages import HumanMessage


class Topic(BaseModel):
    """Punto de conocimiento"""
    name: str = Field(description="Nombre del punto de conocimiento")
    order: int = Field(description="Orden de estudio, comenzando desde 1")
    minutes: int = Field(description="Minutos de estudio recomendados")


class LearningPlan(BaseModel):
    """Plan de estudio"""
    goal: str = Field(description="Resumen del objetivo de estudio")
    level: Literal["Principiante", "Intermedio", "Avanzado"] = Field(description="Nivel de dificultad")
    total_hours: float = Field(description="Duración total (horas)")
    topics: list[Topic] = Field(description="Lista de puntos de conocimiento")


model = init_chat_model("deepseek:deepseek-v4-flash", temperature=0)
agent = create_agent(
    model=model,
    response_format=LearningPlan,
    system_prompt="Eres el planificador de estudios de EJEMPLO Tutorial para Principiantes.",
)

result = agent.invoke({
    "messages": [HumanMessage(
        content="Ayúdame a crear un plan de estudio de Python para principiantes, con una duración total de menos de 10 horas"
    )]
})

plan = result["structured_response"]
print(f"Objetivo: {plan.goal}")
print(f"Dificultad: {plan.level}")
print(f"Duración total: {plan.total_hours} horas")
print(f"\n"Lista de puntos de conocimiento ({len(plan.topics)} puntos):")
for topic in plan.topics:
    print(f" {topic.order}. {topic.name} ({topic.minutes} minutos)")

Resultado de ejecución:

目标: 掌握 Python 基础语法,能够独立编写简单的 Python 程序
Dificultad: 入门
总时长: 9.5 小时

知识点列表 (6 个):
  1. 环境搭建与基础语法 (60分钟)
  2. 数据类型与变量 (90分钟)
  3. 条件判断与循环 (120分钟)
  4. 函数与模块 (120分钟)
  5. 列表与字典 (90分钟)
  6. 综合练习 (90分钟)

Obtener salida estructurada desde mensajes

Si no necesitas la capacidad de llamada a herramientas del Agent y solo quieres extraer información estructurada del texto, puedes usar el modelo directamente:

Ejemplo

from pydantic import BaseModel, Field
from langchain.chat_models import init_chat_model


class SentimentResult(BaseModel):
    """Resultado del análisis de sentimientos"""
    sentiment: str = Field(description="Positivo/Negativo/Neutral")
    score: float = Field(description="Intensidad del sentimiento 0~1")
    keywords: list[str] = Field(description="Palabras clave del sentimiento")


model = init_chat_model("deepseek:deepseek-v4-flash", temperature=0)

# Usar with_structured_output() directamente en el modelo
# No se necesita Agent
structured_model = model.with_structured_output(SentimentResult)

texts = [
    "¡EJEMPLO Tutorial para Principiantes es realmente muy útil, lo recomiendo encarecidamente!",
    "Este tutorial tiene muy poco contenido, no vale mucho la pena.",
    "Hoy hace buen tiempo.",
]

for text in texts:
    result = structured_model.invoke(text)
    print(f"Texto: {text[:30]}...")
    print(f" Sentimiento: {result.sentiment}, Intensidad: {result.score}, Palabras clave: {result.keywords}")

Resultado de ejecución:

Texto: Ejemplo 真的太好用了,强烈推荐!...
  Sentimiento: 积极, 强度: 0.95, 关键词: ['好用', '推荐']
Texto: 这个教程内容太少了,不太值。...
  Sentimiento: 消极, 强度: 0.7, 关键词: ['内容太少', '不太值']
Texto: 今天天气不错。...
  Sentimiento: 中性, 强度: 0.1, 关键词: ['不错']

with_structured_output() es un método del modelo y se puede usar sin Agent. Si tu escenario es "extracción de información" en lugar de "razonamiento de múltiples pasos", usar with_structured_output() directamente es más simple y eficiente.

Otras extensiones