Skip to content

Pedido en lenguaje natural: convertirlo en un carrito de compras estructurado ​

💡 Resumen en una frase: usa Jev para convertir un pedido de una sola frase en un carrito de compras estructurado; el bucle de opciones en contracción de Choice encuentra cada artículo, luego se envía un lote de solicitudes por artículo para completar los campos, y al final el código lo ensambla en tu sistema de pedidos.

El cliente dirá «Can I get a large oat milk latte and a blueberry muffin please» (un latte grande con leche de avena y un muffin de arándanos, por favor), pero tu sistema de caja necesita un carrito de compras estructurado, con cada artículo por separado y cada campo en su sitio. La solución del cookbook oficial Shopping cart usa un solo tipo de pregunta, la pregunta Choice, y completa el paso de lenguaje natural a datos estructurados en dos etapas:

  1. Encontrar los artículos: como de antemano no se sabe cuántos artículos hay, se usa un bucle de opciones en contracción: cada ronda pregunta «¿qué artículo restante se menciona primero en el pedido?», y cada artículo elegido se elimina de las opciones de la siguiente ronda, hasta que el modelo elige la opción centinela nothing_else.
  2. Llenar los campos: al conocer cada artículo, también se conocen sus campos (el latte tiene size y milk); para cada artículo, una solicitud por lote hace todas las preguntas de campos en paralelo.

Prueba oficial (jev-1.14.0, 2026-10-29): 3 solicitudes encuentran los 2 artículos (latte 0.99, muffin de arándanos 1.00, centinela 1.00), más 1 solicitud para completar los dos campos del latte (large 1.00, oat 1.00); en total 4 solicitudes arman todo el carrito. Esta lección se completa en unos 15 minutos, y tras descargar la caché oficial puedes reproducir todos los números oficiales sin configurar una API Key (verificado en esta página).

Qué podrás hacer al terminar ​

  • Escribir find_items(order): dada una orden en lenguaje natural, sin importar cuántos artículos pida, un bucle encuentra cada artículo con su nivel de confianza, y nothing_else el centinela captura el «ya terminó de pedir»
  • Escribir fill_fields(order, item): una solicitud por artículo llena en paralelo todos los campos conocidos, y los campos que el cliente no mencionó se responden explícitamente con unspecified, en lugar de inventar un valor
  • Escribir el menú como datos puros (descripción + schema de campos): para añadir artículos o campos basta con modificar el diccionario, sin cambiar ni una palabra de las preguntas
  • Reproducir los números oficiales sin gastar un centavo: repetición desde la caché oficial json_cache.json, reejecución con cero solicitudes

Por qué usar Jev en lugar de dejar que el LLM genere directamente el JSON del carrito ​

«Que el LLM analice esta frase y la convierta en un JSON del carrito» es la primera reacción de muchos; funciona, pero lo que obtienes es un texto al que hay que rezarle.

CapacidadLLM genera JSONJev Bucle de opciones en contracción
Cantidad de artículos❌ «cuántos pidió» depende de que el modelo cuente; si se equivoca, faltan o sobran ítems✅ el bucle encuentra uno por ronda y se detiene solo al terminar; el conteo lo hace el código
Validez de los campos❌ puede generar venti, 燕麦奶 que no están en tu menú✅ las opciones son los valores válidos (size ∈ small/medium/large), la respuesta siempre cae dentro de las opciones
Campos no mencionados❌ tiende a añadir por el cliente un «medium por defecto»✅ la opción unspecified reporta explícitamente «el pedido no lo dice», y tú decides según tus reglas por defecto
Análisis aguas abajo❌ fallos de parseo del JSON, campos alucinados, validación en cada capa✅ respuestas tipadas + distribución de probabilidades, el código las usa directamente
Nivel de confianza❌ hay que preguntar «¿estás seguro?»✅ cada juicio lleva su propio confidence; los de baja confianza se envían a confirmación manual del personal

En una frase: el LLM reescribe el pedido por ti; Jev solo lee el pedido por ti: cada artículo y cada campo es una pregunta de selección calibrable.

Tu situación actual ​

  • «Dejo que el LLM genere el JSON del carrito; nueve de cada diez veces sale bien, pero la vez que falla el cliente pidió tres artículos y solo escupió dos, y en la queja ni siquiera encuentras qué línea de código falló»
  • «El cliente dice “un latte” sin tamaño, y el modelo cada vez inventa con seguridad un medium y lo escribe en el pedido»
  • «En cuanto el menú se actualiza, hay que modificar el prompt de análisis y luego repetir todas las pruebas de regresión»

Cuándo usar esta técnica ​

Cuando necesitas:

  • Convertir una frase en lenguaje natural en datos estructurados: pedidos, opciones de configuración, llenado de formularios, selección de atributos de productos
  • El conjunto de candidatos es un conjunto cerrado y conocido: el menú lo defines tú, y los valores válidos de los campos también
  • Cantidad indeterminada: puede pedir 1 artículo, puede pedir 5, no se sabe de antemano

Y no quieres:

  • Analizar el JSON que escupe el LLM y luego escribir otra capa de validación de «¿lo volvió a inventar?»
  • Hacer que un modelo generativo cuente: el manual oficial de errores conocidos dice claramente que contar no es confiable y que el error crece con la escala
  • Reajustar el prompt cada vez que cambia el menú

🎒 Preparativos antes de empezar ​

  • Haber completado la pregunta Choice: saber escribir un map de criteria opciones, saber leer choice y confidence, y saber que una pregunta admite como máximo 255 opciones
  • Se recomienda haber leído Confidence (confianza): saber cómo pasar a revisión humana las respuestas de baja confianza
  • Haber completadoInstalación y primera solicitud: .venv está disponible. Esta lección se puede ejecutar por completo sin Key (reproducción de la caché oficial); para ejecutarla en vivo, define TYPESAFE_API_KEY
  • Un vaso de agua ☕ — esta lección es un proyecto pequeño completo: un bucle más un conjunto de preguntas, que convierte «una frase» en «un carrito de compras»

Hazlo conmigo ​

Primero acordemos cómo ejecutarlo: crea cart.py, pega los bloques de código de cada paso siguiente en orden en el mismo archivo, y ejecuta python cart.py cada vez que completes un paso. Todas las llamadas a la API pasan por la caché json_cache.json, así que repetir la ejecución no cuesta nada.

Paso 1: instalar el entorno, descargar la caché oficial y preparar el menú y el pedido ​

Por qué: el oficial grabó una caché de respuestas para todas las 4 solicitudes de este caso json_cache.json; colocándola en la ubicación correcta se puede reproducir todas las cifras oficiales sin llamar a la API; sin ella, define TYPESAFE_API_KEY para ejecutarlo de verdad.

Instala las dependencias (comando original del cookbook oficial; cooksafe es la biblioteca de utilidades oficial complementaria, cuya descripción en PyPI dice «Shared helpers for the TypeSafe cookbooks», y su declaración de dependencias incluye typesafe-sdk<0.8.0,>=0.7.0, así que no hace falta escribir el SDK por separado):

bash
pip install ipython 'cooksafe>=0.2.0,<0.3.0'

Descarga la caché oficial (enlace directo raw; reproducir las cifras oficiales sin definir Key depende por completo de ella):

bash
curl -sL -o json_cache.json https://raw.githubusercontent.com/typesafe-ai/typesafe-public-examples/main/cookbooks/cart_from_primitives/json_cache.json

Crea cart.py y pega el encabezado del archivo — cliente, caché, constantes:

python
import os
from pathlib import Path

from cooksafe import JsonCache, make_playground_link
from IPython.display import Markdown, display
from typesafe_sdk import Choice, TypeSafeClient

TYPESAFE_MODEL = "jev-1.14.0"  # 官方数字的录制版本
NOTHING_ELSE = "nothing_else"  # the sentinel option that ends the item loop
MAX_ITEM_REQUESTS = 6  # a hard stop, so a bad answer can never loop forever

client = TypeSafeClient(
    api_key=os.environ.get("TYPESAFE_API_KEY", "cache-only"),  # cached re-renders need no key
    model=TYPESAFE_MODEL,
    timeout=30.0,
)
json_cache = JsonCache(Path("json_cache.json"))


def fmt_confidence(confidence: float | None) -> str:
    """A confidence for printing. The API can return None, so never format it blind."""
    return f"{confidence:.2f}" if confidence is not None else "n/a"


print("setup ok")

Ejecuta python cart.py.

Deberías ver: setup ok — todavía no se ha enviado ninguna solicitud.

Recuerda primero tres nombres: NOTHING_ELSE es la opción centinela que termina el bucle; MAX_ITEM_REQUESTS = 6 es el límite duro — el comentario oficial lo deja muy claro: evita que una mala respuesta haga que el bucle nunca se detenga; fmt_confidence te recuerda que confidence puede ser None, no lo formatees a ciegas.

  • setup ok se imprimió, json_cache.json está en el directorio de ejecución

Paso 2: escribir el menú como datos — las descripciones son para que las lea Jev, los campos son las opciones ​

Por qué: ¿dónde vive la «estructura» de la conversión de lenguaje natural a datos estructurados? La respuesta oficial es un diccionario: la descripción de cada producto indica cómo lo pediría un cliente (al latte también se le llama flat white o milky coffee), y fields es su propio schema — los nombres de los campos se mapean a listas de valores válidos, y esos valores son las opciones criteria de la pregunta de ese campo. El menú son datos, no un prompt; para añadir novedades basta con modificar el diccionario.

Pega el menú y el pedido:

python
MENU = {
    "latte": {
        "description": "Espresso with steamed milk. Also ordered as a flat white or a milky coffee.",
        "fields": {
            "size": ["small", "medium", "large"],
            "milk": ["whole", "oat", "almond"],
        },
    },
    "filter_coffee": {
        "description": "Plain brewed drip coffee, sometimes ordered as a black coffee.",
        "fields": {},
    },
    "blueberry_muffin": {
        "description": "A blueberry muffin.",
        "fields": {},
    },
    "almond_croissant": {
        "description": "An almond croissant, sometimes ordered as a pastry.",
        "fields": {},
    },
}

ORDER = "Can I get a large oat milk latte and a blueberry muffin please"

Dos puntos de diseño:

  • Las descripciones contienen el lenguaje del pedido: Jev compara el pedido con estas descripciones — si el cliente dice «a milky coffee», lo que coincide es la descripción del latte, no el sentido literal de esa palabra. Por eso la descripción debe escribir «cómo lo diría el cliente» y no «qué es esto»
  • Solo el latte tiene campos: size y milk son cada uno un conjunto cerrado; los otros tres productos no tienen campos, y en el paso 4 se omiten directamente sus solicitudes

Ejecuta python cart.py.

Deberías ver: sigue habiendo solo setup ok — el menú es solo una definición de datos, no se ha enviado ni una solicitud.

  • Puedo explicar el papel de description y de fields en MENU, respectivamente, y por qué la descripción debe incluir sinónimos usados al pedir

Paso 3: bucle de opciones que se contraen — la primera parte de la conversión de lenguaje natural a datos estructurados, encontrar cada producto ​

Por qué: no se sabe de antemano cuántos productos pedirá el cliente. Preguntar directamente «¿cuántos pidió?» es hacer que el modelo cuente — el manual de trampas oficial (versión Jev 1.13, 9 modos de fallo, ver Jev 1.13 manual de trampas) lo dice claramente: Jev no cuenta de forma fiable, y el error crece con el tamaño de lo que se cuenta; la alternativa es que el código itere sobre los candidatos, una pregunta por cada uno. El bucle de opciones que se contraen es exactamente esa práctica: en cada ronda, una pregunta Choice pregunta «¿qué producto restante se menciona primero en el pedido?»; al elegirse, se guarda y se elimina de las opciones de la ronda siguiente, y la frase entera se vuelve a enviar tal cual. Esto también es una dependencia real según el criterio oficial — palabras textuales oficiales: la segunda solicitud solo es una dependencia real cuando el código necesita la respuesta anterior para construir la siguiente solicitud (por ejemplo, para decidir las opciones de la siguiente pregunta).

Primero mira el bucle completo, luego pega el código:

text
Ronda 1  opciones = latte / filter_coffee / blueberry_muffin / almond_croissant + nothing_else
         → latte (0.99)            se guarda, se elimina de las opciones de la ronda siguiente
Ronda 2  opciones = filter_coffee / blueberry_muffin / almond_croissant + nothing_else
         → blueberry_muffin (1.00) se guarda, se elimina de las opciones de la ronda siguiente
Ronda 3  opciones = filter_coffee / almond_croissant + nothing_else
         → nothing_else (1.00)     ← el centinela es elegido, el bucle se detiene

Pega el constructor de preguntas, la función de solicitud única y el bucle principal:

python
def item_question(remaining: dict[str, dict], found: list[str]) -> Choice:
    """Build one request's question from the items not found yet."""
    already = ", ".join(found) if found else "nothing yet"
    criteria = {name: item["description"] for name, item in remaining.items()}
    criteria[NOTHING_ELSE] = (
        "The order mentions no menu item other than the ones already accounted for."
    )
    return Choice(
        instructions=(
            f"This is a cafe order. Items already accounted for: {already}. "
            "Which remaining menu item does the order mention? If the order mentions more "
            "than one remaining item, choose the one mentioned first."
        ),
        criteria=criteria,
    )


@json_cache
def ask_item(order: str, question: dict) -> dict:
    """One item request. The question arrives as its API JSON, which also keys the cache."""
    answer = client.system_one(state=order, questions={"item": question}).choices["item"]
    return {"choice": answer.choice, "confidence": answer.confidence}


def find_items(order: str) -> list[dict]:
    remaining = list(MENU)
    found: list[dict] = []
    item_requests = 0
    for _ in range(MAX_ITEM_REQUESTS):
        if not remaining:
            break
        question = item_question(
            {name: MENU[name] for name in remaining},
            [item["name"] for item in found],
        )
        result = ask_item(order, question.model_dump(mode="json", exclude_none=True))
        item_requests += 1
        print(
            f"item request {item_requests}: {len(remaining)} items + sentinel "
            f"-> {result['choice']} (confidence {fmt_confidence(result['confidence'])})"
        )
        if result["choice"] == NOTHING_ELSE:
            break
        remaining.remove(result["choice"])
        found.append({"name": result["choice"], "confidence": result["confidence"]})
    return found


items = find_items(ORDER)
print(f"\nfound {len(items)} items: {[item['name'] for item in items]}")

Ejecuta python cart.py — todo coincide con la caché oficial, no se envía ni una sola solicitud.

Deberías ver (grabado por el oficial jev-1.14.0; reproducido palabra por palabra en la prueba de esta página):

text
item request 1: 4 items + sentinel -> latte (confidence 0.99)
item request 2: 3 items + sentinel -> blueberry_muffin (confidence 1.00)
item request 3: 2 items + sentinel -> nothing_else (confidence 1.00)

found 2 items: ['latte', 'blueberry_muffin']

Cuatro puntos de diseño merecen una pausa:

  • El centinela es el freno del bucle: Choice debe elegir una opción, no existe «no elegir ninguna» — por eso cada ronda incluye nothing_else, cuya descripción indica claramente «el pedido no menciona productos aparte de los ya contabilizados». Si se elige, el bucle se detiene
  • instructions informa del progreso: «Items already accounted for: nothing yet → latte → latte, blueberry_muffin» — en cada ronda se le dice al modelo qué se ha encontrado antes, para evitar que vuelva a reportar productos ya encontrados
  • «Elige el mencionado primero» elimina ambigüedades: cuando el pedido menciona más de un producto restante, se elige solo el mencionado primero — una regla determinista, no dejar que el modelo improvise
  • Salida con triple seguro: centinela elegido, menú vacío, límite de MAX_ITEM_REQUESTS — el bucle se detendrá sin falta

💡 Este es el valor único de Jev

Esto es un bucle de software, no un bucle de agente — la guía oficial de construcción lo dice claramente: «lo que se pueda expresar con un flujo de trabajo de software, no lo implementes con un bucle while de agente». El flujo de control, las condiciones de salida y la deduplicación están todos en tu código; el modelo solo hace una cosa muy acotada por ronda: elegir uno entre las opciones de esa ronda. Si elige mal, el límite duro del código lo cubre; si elige bien, confidence te dice qué tan sólida fue esa elección.

  • Ejecutar sin Key produce 3 líneas de item request y found 2 items; puedo nombrar las tres condiciones de salida del bucle y el papel de la opción centinela

Paso 4: una solicitud por lote por producto para rellenar los campos ​

Por qué: una vez encontrados todos los productos, queda determinado qué campos preguntar para cada uno — el latte tiene size y milk, el muffin no tiene campos. El enfoque oficial es una solicitud por producto que incluye todas sus preguntas de campos (patrón fan-out: varias preguntas evaluadas en paralelo sobre el mismo estado), en lugar de una solicitud por campo. Además, cada pregunta de campos incluye la opción unspecified — los campos que el cliente no mencionó se responden explícitamente como «el pedido no lo dice», en lugar de verse obligado a elegir un valor concreto.

Pega la construcción de las preguntas de campos y el código de relleno:

python
UNSPECIFIED = "unspecified"


def field_questions(item_name: str) -> dict[str, Choice]:
    questions = {}
    for field, values in MENU[item_name]["fields"].items():
        criteria = {value: None for value in values}
        criteria[UNSPECIFIED] = (
            f"The order does not say which {field} for the {item_name}."
        )
        questions[field] = Choice(
            instructions=f"Which {field} did the order ask for, for the {item_name}?",
            criteria=criteria,
        )
    return questions


@json_cache
def ask_fields(order: str, questions: dict[str, dict]) -> dict:
    """One field request. The questions arrive as their API JSON, which also keys the cache."""
    response = client.system_one(state=order, questions=questions)
    return {
        field: {"choice": answer.choice, "confidence": answer.confidence}
        for field, answer in response.choices.items()
    }


def fill_fields(order: str, item_name: str) -> dict:
    if not MENU[item_name]["fields"]:
        return {}
    questions = {
        field: question.model_dump(mode="json", exclude_none=True)
        for field, question in field_questions(item_name).items()
    }
    return ask_fields(order, questions)


cart = []
for item in items:
    fields = fill_fields(ORDER, item["name"])
    cart.append(
        {"name": item["name"], "confidence": item["confidence"], "fields": fields}
    )

Ejecuta. El latte hace 1 solicitud (las dos preguntas size + milk en paralelo), y fields del muffin de arándanos queda vacío—se omite la solicitud directamente. Sumando las 3 solicitudes del paso 3, todo el caso usa 4 solicitudes en total.

Deberías ver: no hay salida nueva—este paso solo ensambla la lista cart en memoria (el latte con las respuestas de sus dos campos, el muffin con fields como diccionario vacío); el paso 5 es el que imprime.

  • Puedo explicar por qué el muffin no envía solicitudes y qué tipo de problema de «valores por defecto inventados» resuelve la opción unspecified

Paso 5: el código ensambla el carrito estructurado ​

Por qué: el ensamblado es tarea de código puro, sin una sola llamada a la API. Cada artículo lleva su propia confidence, y cada campo también—se ve de un vistazo qué juicio se queda atrás.

Pega el código de impresión:

python
print(f'order: "{ORDER}"\n')
for line in cart:
    print(f"{line['name']}  (item confidence {fmt_confidence(line['confidence'])})")
    for field, answer in line["fields"].items():
        conf = fmt_confidence(answer["confidence"])
        print(f"    {field:<6} {answer['choice']:<12} confidence {conf}")

Ejecuta.

Deberías ver (grabado por el oficial jev-1.14.0; reproducido palabra por palabra en la prueba de esta página):

text
order: "Can I get a large oat milk latte and a blueberry muffin please"

latte  (item confidence 0.99)
    size   large        confidence 1.00
    milk   oat          confidence 1.00
blueberry_muffin  (item confidence 1.00)

Verifica contra el schema del menú del paso 2: el artículo es una key válida del menú, size es large (uno de los valores válidos), milk es oat (uno de los valores válidos)—es imposible que aparezca un artículo o valor de campo fuera del menú, porque las respuestas solo pueden elegirse de entre las opciones. Esa es la confianza de lo «estructurado»: el sistema de pedidos downstream siempre recibe datos dentro del schema.

  • Mi salida coincide literalmente con las cifras oficiales: latte 0.99 / large 1.00 / oat 1.00 / blueberry_muffin 1.00

📋 Prompt mágico ​

El «Prompt» de esta página es una plantilla de preguntas para la API—cópiala, sustituye los marcadores 【】 (los que llevan ? son opcionales) y podrás conectarla a tu propio menú o catálogo de productos. El trío: pregunta de búsqueda de artículo, preguntas de campos, esqueleto de bucle.

📝 Pregunta de búsqueda de artículo (versión Choice contraída) ​

Efecto esperado: cualquier necesidad de «encontrar en una frase todas las entradas conocidas que coincidan»—pedidos, selección de opciones de configuración, marcar servicios—usa esta pregunta, dentro de un bucle para encontrarlas una por una.

python
from typesafe_sdk import Choice

# 必填项:remaining 传还没找到的商品(名字 -> 顾客会怎么点它的描述)
criteria = {【name】: 【商品描述,写顾客的同义叫法】 for name in 【remaining】}
criteria[【哨兵名】] = "【订单里没有提到已算过之外的商品】"
item_q = Choice(
    instructions=(
        f"【这是什么场景的一句话。已算过的:{【found 或 'nothing yet'】}。】"
        "【订单里最先提到的剩余商品是哪样?提到多件时选最先说的】"
    ),
    criteria=criteria,
)
# 选填项:场景词换掉 cafe order——配置单、服务预约、商品咨询?
# 输出规范:answer.choice 是商品名或哨兵名;answer.confidence 接复核线
# 约束条件:
# ✅ 描述写「顾客会怎么点它」,同义词写进去(flat white 也是 latte)
# ✅ 每轮把已找到的报进 instructions,防止重复报
# ❌ 别问「她点了几样」——计数交给循环,模型只做挑选

✅ Preguntas de campos (versión schema de campos) ​

Efecto esperado: convierte los valores válidos de los campos de cada artículo en Choice pregunta por pregunta, todas en paralelo en una sola solicitud; los campos que el cliente no mencionó se reportan explícitamente como unspecified.

python
# 必填项:fields 是该商品的 schema:字段名 -> 合法值列表
questions = {}
for field, values in 【商品["fields"]】.items():
    criteria = {value: None for value in values}
    criteria[【"unspecified"】] = f"The order does not say which {field} for the {【商品名】}."
    questions[field] = Choice(
        instructions=f"【订单为这个商品点了哪个 {field}?】",
        criteria=criteria,
    )
# 选填项:unspecified 的下游处理——按你的默认值规则补,或转人工确认?
# 输出规范:每字段 answer.choice ∈ 合法值 ∪ {unspecified},各带 confidence
# 约束条件:
# ✅ 选项就是函数/系统接受的合法值——答案不可能越界
# ✅ 没有字段的商品跳过请求,别发空请求
# ❌ 不给 unspecified = 逼模型编一个值

🔧 Esqueleto de bucle (versión código) ​

Efecto esperado: encontrar todos los artículos en cantidad indefinida, evitar bucles infinitos, ahorrar con caché—un fragmento de código puro, testeable de forma aislada.

python
MAX_REQUESTS = 【6:硬上限,防坏答案死循环】
remaining, found = list(【MENU】), []
for _ in range(MAX_REQUESTS):
    if not remaining:
        break
    result = ask(【order】, build_question(remaining, found))
    if result["choice"] == 【哨兵名】:
        break
    remaining.remove(result["choice"])
    found.append(result)
# 输出规范:found 是 [{name, confidence}, ...];件数 = len(found),由代码数
# 约束条件:
# ✅ 三个出口缺一不可:哨兵、候选清空、硬上限
# ✅ 请求函数挂 @json_cache——改菜单/改问题会换缓存键自动真跑,重跑零花费
# ❌ 别把循环交给模型自己「决定何时结束」——退出条件是代码的事

Punto de control ✅ ​

  • Sin definir TYPESAFE_API_KEY y con el json_cache.json oficial en su lugar, reproduje literalmente todas las cifras oficiales: latte 0.99 / blueberry_muffin 1.00 / nothing_else 1.00 / size large 1.00 / milk oat 1.00
  • Todo el caso usa 4 solicitudes en total: 3 de búsqueda de artículos (incluida 1 de centinela) + 1 para los campos del latte; el muffin no envió solicitudes
  • Puedo explicar por qué se usa un bucle en lugar de preguntar «¿cuántos artículos pidió?»: el conteo no es fiable, la iteración en código + una pregunta por artículo es el enfoque alternativo oficial
  • Puedo explicar que esto es una «dependencia real»: las opciones de la siguiente ronda solo pueden construirse esperando la respuesta de la ronda anterior—exactamente la situación que el criterio oficial reconoce como justificada para una segunda solicitud
  • Sé la división de tareas entre unspecified y nothing_else: el primero indica un campo no mencionado, el segundo que ya no quedan artículos por encontrar

Advertencias de errores comunes ​

❌ Hacer que el modelo genere el JSON completo del carrito ​

Una sola generación mezcla tres cosas: conteo, validez de campos y formato: cuenta mal las unidades, inventa valores fuera del menú como venti, el JSON falla al parsear—y si algo sale mal, no se sabe en qué eslabón fue. El desglose oficial deja cada cosa testeable por separado: las unidades las cuenta el bucle, la validez la garantizan las opciones, el ensamblado lo hace el código. Un modelo generativo no puede dar esta garantía, porque cada una de sus palabras se escribe de nuevo.

❌ Olvidar la opción centinela o el límite duro ​

Sin nothing_else, el Choice se ve obligado a elegir uno de los artículos restantes—un pedido ya terminado «gana» un artículo extra. Sin MAX_ITEM_REQUESTS, una mala respuesta puede hacer que el bucle nunca se detenga. Escribe ambos y el bucle será correcto y necesariamente terminante.

❌ En un campo que el cliente no mencionó, el modelo elige por ella ​

Sin una salida unspecified, el modelo solo puede elegir un valor concreto—«un latte» se convertirá con confianza en medium whole milk latte. La solución oficial es que cada pregunta de campo incluya unspecified, y que el downstream complete según tus reglas de valores por defecto o lo pase a confirmación del personal. Otro enfoque oficial para el mismo escenario se ve en decisiones del Agent: el cookbook de function calling usa una pregunta aparte de sí/no para determinar «¿el usuario mencionó este parámetro o no?», y elige una de las dos salidas.

❌ Poner en producción directamente un pedido en chino ​

Nota oficial: Jev está entrenado principalmente en inglés y su precisión es máxima en inglés; otros idiomas (incluido el chino) funcionan pero con menor precisión—antes de salir a producción, ejecuta un lote con tus propios pedidos en chino para ver la distribución de probabilidades, prestando especial atención a confidence; la nota sobre soporte de idiomas está enmodelos y precios. Además, cambiar el menú o las preguntas cambia la clave de caché: la clave de caché de cooksafe se compone del nombre de la función y los parámetros, así que tras cambiar MENU una nueva ejecución hará solicitudes reales automáticamente (solo tendrá éxito si definiste una Key); para forzar una nueva ejecución, borra json_cache.json.

Técnicas avanzadas (opcional) ​

Cantidad: añade un campo quantity. La documentación oficial señala la limitación de este ejemplo: el carrito no tiene campo de cantidad, y «two flat whites» también produce solo un latte. La solución oficial: añade el campo quantity al schema de cada artículo, con valores válidos como one / two / three—la solicitud por lotes del paso 4 lo preguntará automáticamente junto con el resto.

Menús grandes: primero divide en bloques, luego elige. Un Choice admite como máximo 255 opciones (pregunta Choice tiene la explicación completa). Con menús más grandes, elige primero el bloque (qué categoría) y luego el artículo dentro del bloque—cada tramo queda dentro de 255. La búsqueda línea por línea de búsqueda y coincidencia es este mismo enfoque en la práctica: etiqueta cada una de las 218 líneas con un ID y haz que el Choice apunte a la línea que coincide.

Pruébalo primero sin código. Al final de la página oficial del cookbook hay enlaces compartidos de Playground ya preparados—pedido completo + la primera ronda de búsqueda de artículos (cuatro artículos más el centinela); ábrelo (https://console.typesafe.ai/playground), cambia la redacción del pedido y las respuestas cambian con ello. Para generar tu propio enlace:

python
playground_link = make_playground_link(ORDER, {"item": item_question(MENU, [])})
# Print a usable URL in a script; render a clickable link in a notebook.
if __name__ == "__main__" and "__file__" in globals():
    print(f"Open in the TypeSafe playground:\n{playground_link}")
else:
    display(Markdown(f"🔗 [Open the first item-finding request in the TypeSafe playground]({playground_link})"))

La generación del enlace se hace sin conexión y no necesita API Key; la URL lleva el state completo y las preguntas, no pongas datos sensibles. Mira la grabación oficial: TypeSafe shopping cart demo.

Conéctalo a tu flujo de pedidos. Sustituye ORDER por mensajes de chat, transcripciones de voz o notas de formularios, y MENU por tu catálogo de productos; la estructura de las respuestas no cambia y el sistema de pedidos downstream lo acepta tal cual. ¿Más campos suben el costo? preguntas en paralelo y fan-out especulativo midió el beneficio de preguntar en lote: 13 preguntas en una sola solicitud cuestan 12.2 veces menos y son 10.0 veces más rápidas que preguntar una por una, sin cambiar las respuestas.

Resumen de la lección ​

✅ De lenguaje natural a estructurado, el enfoque oficial se divide en dos partes: un bucle de Choice contraído para encontrar artículos (el conteo lo hace el código, el centinela nothing_else frena), y una solicitud por lote por artículo para rellenar campos (los valores válidos son las opciones, unspecified reporta «no mencionado»).

✅ Cada juicio es calibrable: artículo 0.99 / 1.00, campo 1.00 / 1.00—los juicios de baja confianza se envían a confirmación manual del personal, en lugar de entrar directamente al pedido.

✅ Reproducción de las cifras oficiales sin Key: las 4 solicitudes (3 para buscar productos + 1 para rellenar campos) dieron todas en el caché oficial; esta página lo reproduce textualmente en pruebas reales.

✅ El menú son datos, no un prompt: para lanzar novedades se cambia el diccionario MENU sin tocar una sola palabra de las plantillas de preguntas; si se cambia, la clave de caché se renueva automáticamente y se ejecuta de verdad.

Repaso de los campos de configuración clave:

CampoValor en esta páginaExplicación
TYPESAFE_MODEL"jev-1.14.0"Versión con cifras oficiales grabadas (2026-10-29); la ejecución live bloquea el ID de versión, no uses el jev-latest que puede variar
NOTHING_ELSE"nothing_else"Opción centinela: se selecciona cuando no quedan productos en el pedido y detiene el bucle
MAX_ITEM_REQUESTS6Límite máximo estricto: tercera capa de seguridad además del centinela y del menú vacío
UNSPECIFIED"unspecified"Salida cuando no se menciona un campo, evita que el modelo invente valores por defecto
MENU4 productos de muestra; solo el latte tiene size/milkLa descripción recoge cómo pide el cliente; fields es el schema
Solicitudes por pedidoN+1 búsquedas de producto + 1 por cada producto con camposEn este ejemplo 3+1=4; todo por caché, solo hay miss si se cambia el menú o las preguntas

Tutoriales relacionados:

Avance de la próxima lección ​

Un pedido de una frase se convirtió en un carrito; el siguiente problema es cuáles de un montón de candidatos coinciden de verdad. Próxima lección: Búsqueda y coincidencia: reordenamiento, búsqueda línea por línea, alineación de entidades.

Aprenderás:

  • El reordenamiento sube los aciertos top-1 de las consultas legales CLERC del 5% al 18%, y el top-10 del 38% al 62%
  • Búsqueda semántica línea por línea de las 218 líneas de los ToS de GitHub: se asigna un ID a cada línea y una Choice apunta a la línea que coincide——la versión a gran escala del «las opciones son los candidatos» de esta página
  • Cómo encontrar el mismo artículo entre los 450 pares candidatos de dos catálogos de cervezas con un Score y tres Noul
gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.