Skip to content

Estado (State): qué material darle a Jev ​

Una solicitud de Jev solo tiene dos cosas: state (el contenido a evaluar) + questions (preguntas tipadas). Esta lección cubre la primera mitad: cómo preparar el Jev state: cómo elegir entre las tres formas, cómo organizar un ticket estructurado y qué detalles no deberías incluir.

En realidad, ya escribiste un state en la primera solicitud: la cadena del ticket dentro de route_ticket.py era exactamente eso. Esta lección lo sube de nivel a un material fácil de evaluar en 8 minutos.

Qué podrás hacer al terminar ​

  • Elegir una de las tres formas del Jev state según la forma del material: cadena para un fragmento de texto, objeto JSON para múltiples campos, matriz de texto para múltiples entradas homogéneas
  • Organizar un ticket (conversación + pedido + política) en un state estructurado, donde cada campo tiene nombre y las relaciones son claras
  • Usar dot path (rutas entre comillas invertidas como `ticket.messages[0].text`) para que las questions apunten con precisión a campos del state
  • Mencionar los dos límites de contexto del state (64k por solicitud / 32k por pregunta) y las cuatro reglas estrictas del cuerpo de la solicitud
  • Explicar por qué «enviar solo los campos que necesita cada pregunta» ahorra dinero y mejora la precisión

Tu situación actual ​

  • Pego la conversación completa del usuario tal cual en el prompt para que GPT decida a qué grupo derivarla: la mitad de los tokens son «¿estás ahí?», «gracias» y la firma; la factura se duplica y el resultado de la clasificación a veces se desvía por el nombre de la empresa en la firma
  • El ticket claramente tiene varios campos (título, cuerpo, nivel del cliente), pero solo puedo pegarlos en el prompt como un gran bloque «esto es un ticket, el título es… el cuerpo es…»: cuando hay muchos campos se me olvidan algunos, y si el modelo responde mal no sé distinguir si fue por material mal dado o porque no lo entendió
  • El material y los criterios de evaluación están mezclados en el mismo prompt: si quiero preguntar algo más como «¿esto es grave?», tengo que copiar y reenviar todo el material; si quiero que el modelo mire solo el campo «cuerpo», solo puedo escribir «ignora la parte del título», y que lo haga o no es pura suerte

Cuándo usar esta técnica ​

Cuando necesitas:

  • Preparar material para cada evaluación de Jev: el state es lo único que el modelo puede ver
  • El material tiene estructura (múltiples campos, múltiples entradas) y no quieres pegarlo en un gran bloque de texto
  • Quieres hacer varias preguntas sobre el mismo material y controlar con precisión qué campos ve cada pregunta

Y cuando no quieres:

  • Mezclar instrucciones de evaluación, políticas de referencia y el texto a evaluar en el mismo prompt
  • Pagar tokens de entrada por contenido irrelevante (Jev cobra por tokens de entrada)
  • No poder distinguir qué parte del material introdujo el ruido cuando el modelo responde mal

🎒 Preparativos antes de empezar ​

  • Haber completado la guía de uso diario: conocer la ruta de esta sección — primero aprender a dar material (esta lección), luego los cinco estilos de preguntas
  • Haber ejecutado la primera solicitud: .venv tiene instalado typesafe-sdk y la variable de entorno TYPESAFE_API_KEY ya está configurada
  • Recordar el aspecto general de route_ticket.py (client.system_one(state=..., questions=...)); si lo olvidaste, vuelve y échale un vistazo

Idea central ​

La definición oficial en una frase: state es el contenido que le pides al modelo System One que evalúe — puede ser un mensaje de soporte, un fragmento de texto o el estado actual de tu aplicación. Se pasa a través del campo state de la solicitud, junto con las preguntas (docs.typesafe.ai/concepts/state.md).

Un modelo mental útil, con las palabras oficiales:

Imagina el state como el material que presentas a un panel de expertos antes de pedirles que hagan una evaluación.

¿Cómo prepararías el material para un panel de expertos? Escribir títulos claros, adjuntar el historial de pedidos tal cual, poner las políticas en una página aparte — en lugar de mezclar las tres cosas en un solo párrafo. Esa es la línea principal de toda esta lección.

Primero mira en qué se diferencia del contexto del prompt que ya conoces:

prompt de un LLM de chatJev state
Material e instruccionesmezclados en un solo texto; cambiar la pregunta exige reenviar todoel state solo contiene material, las questions se definen aparte
Referencia a camposdepende de «mira el segundo párrafo», «ignora el título»dot path apunta con precisión al campo, como `ticket.body`
Contenido irrelevantese lee todo lo que se pegue; saludos y firmas cuentan como tokenssolo se ponen los campos necesarios para la evaluación, el recorte tiene fundamento
Reutilizacióncambiar la evaluación implica reescribir todo el bloqueel mismo state se usa repetidamente con varias preguntas

Y hay un hecho que atraviesa toda la lección: Jev cada solicitud solo ve el state que le envías, no tiene memoria implícita — lo que el cliente te dijo el mes pasado, si no lo pones en el state de esta vez, no lo sabrá (esto es justamente lo que hará el escenario posterior de sistema de memoria básico).

Hazlo conmigo ​

Paso 1: envía una solicitud con el state de cadena más simple ​

Por qué: el state más simple es un fragmento de texto plano; úsalo primero para confirmar en 30 segundos la sensación de que «state = material».

El ejemplo más simple de la documentación es justamente esta cadena:

python
state = "My card was charged twice."

Combinada con aquella pregunta de billing de la documentación, forma una solicitud completa:

python
# 运行前:export TYPESAFE_API_KEY="<你的API Key>"
# 安装:pip install typesafe-sdk(注意包名是连字符,import 是下划线 typesafe_sdk)
from typesafe_sdk import Noul, TypeSafeClient

state = "My card was charged twice."

with TypeSafeClient(model="jev-latest") as client:  # 自动读 TYPESAFE_API_KEY
    response = client.system_one(
        state=state,
        questions={
            "billing": Noul(instructions="Is this message about billing?"),
        },
    )

print(response.answers["billing"].noul)

Deberías ver: el script imprime un número entre 0 y 1. En la documentación oficial de OpenAPI hay un ejemplo casi idéntico: state es "I was charged twice for my subscription this month. Please refund the extra charge.", la pregunta es "Is this message about billing?" y devuelve noul: 0.98. Una solicitud de reembolso claramente formulada obtuvo una probabilidad de billing de 0.98; tu valor concreto depende de la salida real.

  • El script de arriba se ejecuta correctamente e imprime un número entre 0 y 1

Paso 2: actualizar el state de Jev de cadena a objeto JSON estructurado ​

Por qué: la recomendación oficial es usar un objeto para la mayoría de las solicitudes—«dar a cada parte del state un nombre descriptivo y mantener claras las relaciones» (Use an object for most requests). La cadena solo es adecuada cuando el caso de uso es simple y hay un único fragmento de texto.

Tabla comparativa oficial de las tres formas:

FormaCuándo usarlaEjemplo
CadenaUn mensaje, un artículo, un fragmento de texto"My card was charged twice."
Objeto JSONCampos con nombre, registros relacionados, estado de la aplicación{"message": "…", "order_id": "A-104"}
Array de textosUna serie de mensajes o registros["Hi", "My customer number is TS1337.", "My card was charged twice."]

En cuanto el material a evaluar se complica, salen a la luz las debilidades de la cadena:

State como cadenaState como objeto JSON
Referencia con dot pathSolo puede apuntar al conjuntoCada campo puede ser referido individualmente por una pregunta
Base del juicioEl modelo lo busca por sí mismo en todo el textoEl nombre del campo aporta la semántica; el juicio corresponde a campos
Adecuado paraJuicios simples de un único textoJuicios complejos con múltiples campos, varias preguntas en paralelo

El ejemplo estructurado oficial es un ticket de soporte: una conversación, un pedido y una política de reembolso, metidos en un solo state:

python
# 运行前:export TYPESAFE_API_KEY="<你的API Key>"
from typesafe_sdk import TypeSafeClient

state = {  # 官方文档例子:docs/concepts/state.md
    "ticket": {
        "subject": "Duplicate charge",
        "messages": [
            {"from": "customer", "text": "I was charged twice for order A-104. Please refund the duplicate."},
            {"from": "support", "text": "We are checking the charges."}
        ]
    },
    "order": {
        "id": "A-104",
        "charges": [
            {"amount_usd": 49, "status": "captured"},
            {"amount_usd": 49, "status": "captured"}
        ]
    },
    "refund_policy": "Duplicate charges are eligible for a refund."
}

Fíjate en dos cosas:

  • Esto es un solo state, aunque incluye tres bloques: conversación, pedido y política; la recomendación oficial es «cuando la decisión requiere comparar estas partes, coloca la información relacionada junta»
  • En Python, las cadenas, diccionarios y listas se pasan directamente a client.system_one(state=...), sin necesidad de serializarlos a una cadena JSON

Deberías ver: el state es simplemente un diccionario Python normal, y todavía no se ha producido ninguna solicitud de red; este paso solo prepara el material. refund_policy forma parte del material a evaluar, por eso no se escribe como prompt en las instructions (se desarrolla en la siguiente sección).

  • Saber explicar por qué el refund_policy del state no se escribe como prompt en las instructions: porque forma parte del material a evaluar, no es una pregunta (se desarrolla en la siguiente sección)

Paso 3: usar dot paths para que las questions apunten a campos concretos del state de Jev ​

Por qué: una vez que el state pasa a ser un objeto, hace falta una forma de decirle al modelo «esta pregunta solo mira este campo». Sintaxis oficial: en instructions escribe el nombre del campo como una ruta de puntos/índices envuelta en backticks.

python
# 运行前:export TYPESAFE_API_KEY="<你的API Key>"
questions = {  # 官方文档例子:docs/primitives.md「Reference specific fields」
    "refund_requested": {
        "type": "noul",
        "instructions": "Does `ticket.messages[0].text` request a refund?",
    },
    "policy_supports_refund": {
        "type": "noul",
        "instructions": (
            "Does `refund_policy` support the refund requested "
            "in `ticket.messages[0].text`, given `order.charges`?"
        ),
    },
}

with TypeSafeClient(model="jev-latest") as client:
    response = client.system_one(state=state, questions=questions)

print(response.answers["refund_requested"].noul)
print(response.answers["policy_supports_refund"].noul)

El esqueleto de la respuesta se ve así (tres campos de nivel superior model / answers / usage; una pregunta Noul solo devuelve los dos campos type y noul; los nombres de campo provienen del schema oficial, y el significado de los marcadores se explica más abajo):

json
{
  "model": "<实际回答该请求的模型 ID,别名会解析成版本号,如 jev-1.14.0>",
  "answers": {
    "refund_requested": {
      "type": "noul",
      "noul": "<0 到 1 之间的概率>"
    },
    "policy_supports_refund": {
      "type": "noul",
      "noul": "<0 到 1 之间的概率>"
    }
  },
  "usage": {"input_tokens": "<整数>", "output_tokens": "<整数>"}
}

La regla aquí:

  • `ticket.messages[0].text` = ruta de puntos + índice de array, apunta al primer mensaje del cliente
  • Una pregunta puede referir varios campos: policy_supports_refund usa a la vez refund_policy, ticket.messages[0].text y order.charges
  • Esto es la separación entre contenido y preguntas: el state contiene el contenido y los hechos de apoyo (ticket, pedido, política), y las questions definen el juicio. Cambiar las preguntas no obliga a tocar el state, y añadir una pregunta más no exige reenviar el material

Deberías ver: dos líneas de salida, cada una una probabilidad entre 0 y 1; la estructura de la respuesta se ve en el esqueleto de arriba (la documentación oficial no proporciona los valores concretos, guíate por tu salida real).

Al mismo state se le pueden colgar tantas preguntas como se quiera, e incluso mezclar tipos de pregunta: todas las preguntas se evalúan sobre el mismo state de forma paralela e independiente, y añadir preguntas casi no aumenta el tiempo de respuesta (esto se desarrolla en la lección de preguntas en paralelo).

  • Saber escribir el dot path que apunta al importe del segundo cargo en order.charges: `order.charges[1].amount_usd`

Paso 4: recortar tu state dentro de los límites de contexto ​

Por qué: más state no es mejor; está sujeto a límites estrictos y afecta directamente tanto a la precisión como a la factura.

Dos límites de contexto (Jev 1.14 / 1.13 idénticos):

LímiteSignificadoValor por defecto
per-request contextstate + todas las preguntas sumadas64k tokens
per-question contextstate + cualquier pregunta individual32k tokens

Puntos clave:

  • No hay límite en la cantidad de preguntas, la restricción solo mira el tamaño: basta con que ambos contextos lo admitan
  • El state suele ser la parte más pesada (las preguntas suelen ser cortas), y además ambos límites incluyen el propio state: lo primero que suele reventar no son las preguntas, sino el state
  • El state se paga partida por partida: los tokens de entrada de toda la solicitud (state + todas las preguntas) se facturan una sola vez, pero cada campo irrelevante que metas cuesta dinero real
  • Si de verdad te pasas: añadir la cabecera de solicitud TypeSafe-Danger-Zone-Long-Context: true sube ambos límites a 262k, pero el aviso oficial dice que es «más lento y menos preciso, actívalo solo en las solicitudes que lo necesiten»; lo correcto es recortar primero, y el contexto largo es el último recurso (véase modelos y precios)

Además del contexto, el cuerpo de la solicitud tiene cuatro reglas estrictas (docs.typesafe.ai/api/errors):

ReglasLímites
Tamaño del cuerpo de la solicitud≤ 32 MiB (sin incluir los encabezados)
CodificaciónUTF-8 JSON, sin BOM
Anidamientostate / instructions / criteria máximo de 64 niveles cada uno; más profundo hay que aplanarlo
Númerossolo se aceptan números finitos: NaN, Infinity y 1e400 serán rechazados; los ID y los números grandes se pasan como cadenas

El último punto es el que más muerde: los números de pedido y los ID de usuario de los tickets, al ponerlos en state, escríbelos como cadenas como "A-104", no como números sin comillas.

Cómo recortar: el principio de diseño oficial se resume en una frase: «incluye solo el contexto relevante para el problema actual, para ayudar al modelo a evitar distracciones y el context rot». Concretamente, tres trucos:

  1. Filtra antes de enviar: filtra primero en el código los campos que necesita este problema; no metas la fila completa de la base de datos tal cual
  2. No conviertas JSON en cadena: los esquemas, los árboles de categorías y las filas de base de datos ya son JSON; pásalos completos o solo los subcampos relevantes, no los serialices dentro de una plantilla de cadena
  3. Cuando no puedas filtrar en el código, usa un Noul previo para filtrar: pregunta primero «¿este fragmento es relevante para el juicio?» y envía solo lo relevante al siguiente lote de preguntas (así es como funciona el filtro de pasajes RAG)

Lo que se ahorra no son solo tokens. Jev cobra por tokens de entrada y la salida es gratis, y el manual oficial de errores comunes lo dice directamente: cuanta más información irrelevante haya en state, menor es la precisión; los detalles irrelevantes son distractores y además te impiden localizar dónde está el error (se desarrolla en la siguiente sección).

  • Antes de escribir el state, poder responder: «¿qué campos necesita realmente este problema?» Si no puedes responder, no lo envíes todavía

Punto de control ✅ ​

  • Poder describir las tres formas de state y sus escenarios de uso (cadena = un fragmento de texto, objeto = varios campos, array = múltiples entradas homogéneas)
  • Poder escribir un dot path que apunte a cualquier campo de un state estructurado (incluidos índices de array)
  • Conocer los dos valores por defecto de los límites de contexto: 64k por solicitud / 32k por pregunta, y ambos incluyen el propio state
  • Saber que los ID como los números de pedido deben ir en state como cadenas, no como números sin comillas
  • Que en state no haya cortesías, firmas ni tramos enteros de registros sin filtrar ajenos al juicio

Aviso de errores comunes ​

❌ Error 1: tratar un state grande como «cuanto más completo el contexto, mejor» ​

Síntoma: pensando que «dar más contexto nunca está de más», se meten en state todos los tickets históricos del cliente, las cortesías del chat y las firmas.

Por qué está mal: el manual oficial de errores comunes (aplicable a jev-1.13) lo lista como un modo de fallo conocido: «cuanto más contenido ajeno a la decisión haya en state, menor es la precisión; los detalles irrelevantes son distractores, y un state grande hace más difícil localizar qué parte de la entrada causó la respuesta errónea». Los tokens de entrada extra que gastas compran menor precisión.

Solución correcta: filtra en el código antes de enviar y envía solo los campos que necesita el problema; si no puedes filtrar en el código, usa primero un Noul para preguntar por la relevancia y luego filtra.

❌ Error 2: referenciar campos con rodeos en la pregunta ​

Síntoma: para no aprender dot path, se escribe en instructions «mira el campo text del primer elemento del array messages anidado bajo ticket en state».

Por qué está mal: la entrada de Indirection (referencia indirecta) del manual oficial de errores comunes: las instructions que requieren razonamiento de varios saltos o dobles negaciones responden de forma menos fiable.

Solución correcta: usa directamente la ruta entre comillas inversas `ticket.messages[0].text`, señalando el campo en un solo paso.

❌ Error 3: escribir los criterios de juicio dentro de state ​

Síntoma: state = {"text": "判断这条工单是不是退款诉求:我订的东西三天没到"}.

Por qué está mal: las instrucciones de juicio mezcladas con el material obligan a rehacer el state al cambiar de pregunta; tampoco es para esto que sirve state: state contiene contenido y hechos de apoyo, y el juicio se escribe en las instructions y criteria de questions.

Solución correcta: state = {"subject": "物流延迟", "body": "我订的东西三天没到"}, con la pregunta escrita en questions y apuntando de vuelta con un dot path a body. Igual con las reglas del dominio: codifícalas en instructions y criteria, no las apiles debajo del state.

❌ Error 4: pasar ID como números sin comillas ​

Síntoma: {"order_id": 1000042}: por comodidad, se pone el ID entero de la base de datos directamente en state.

Por qué está mal: las reglas de números de la API solo aceptan números finitos: NaN, Infinity y números demasiado grandes para representar (como 1e400) se rechazan directamente (400); al mismo tiempo, la recomendación oficial dice explícitamente «pasa los identificadores y los números grandes exactos como cadenas». Un ID es un identificador, no una cantidad; un número sin comillas incumple fácilmente las reglas de números y carece de la legibilidad de "A-104".

Solución correcta: ID y números grandes exactos siempre como cadenas: {"order_id": "1000042"}.

❌ Error 5: no se puede instalar typesafe-sdk / error al importar ​

Síntoma: pip install typesafe se instala, pero from typesafe_sdk import ... da ModuleNotFoundError.

Por qué está mal: ese typesafe de PyPI es un paquete ajeno con el mismo nombre. El nombre del paquete pip lleva guiones typesafe-sdk, y el import lleva guiones bajos typesafe_sdk.

Solución correcta: pip install typesafe-sdk, y luego from typesafe_sdk import Noul, TypeSafeClient.

Técnicas avanzadas (opcional) ​

🔧 Las imágenes también pueden ir en state. Las imágenes pueden aparecer en cualquier lugar donde pueda aparecer texto: state, instructions y criteria; un state puede mezclar texto e imágenes, contener varias imágenes y llevar etiquetas o anidarse como cualquier otro dato. Desactivado por defecto; hay que añadir el encabezado TypeSafe-Danger-Zone-Images: true a cada solicitud con imágenes, y desde la versión v0.7.5 del SDK de Python se puede poner directamente en state un objeto Image. Ten en cuenta que oficialmente está marcado como «dreamer-ready» (experimental, el formato y la precisión pueden cambiar); consulta Box e imágenes.

🔧 El audio y el vídeo no valen, pero se pueden convertir. Jev no acepta audio ni vídeo; la recomendación oficial es convertirlos a texto o a campos estructurados antes de ponerlos en state.

🔧 Las respuestas pueden entrar en el state del siguiente relevo. Las respuestas de Jev son en sí mismas valores tipados: tu código puede compararlas, aplicarles umbrales, ordenarlas o ponerlas en el state de solicitudes posteriores. Así funciona el cookbook oficial del sistema de memoria: un state por ticket, con el contenido digno de recordar junto con las respuestas de Jev añadidas al state antes de la siguiente llamada (ver sistema de memoria simple).

🔧 El state en chino funciona, pero vigila de cerca el confidence. El inglés es el idioma principal de entrenamiento de Jev y el de mayor precisión; el chino CJK está soportado pero con menor precisión: la recomendación oficial es probar con tus propios datos antes de lanzar contenido no inglés, prestando especial atención al confidence. Esto aplica aún más al enrutar juicios.

Resumen de la lección ​

✅ Vuelve a mirar «qué sabrás hacer al terminar»: las tres formas, la organización estructurada, los dot path, los dos límites de contexto y filtrar antes de enviar; ahora deberías poder cumplirlos punto por punto.

Resumen en una frase: Jev state es el único material que el modelo puede ver: elige la forma según la forma del material, escribe el juicio en questions apuntando de vuelta a los campos con dot path, y dentro de los límites de contexto no metas ni un detalle irrelevante.

Repaso de los puntos clave:

Puntos clavePráctica recomendadaExplicación
Forma del stateUsa un objeto JSON para escenarios con muchos camposLos campos tienen nombres y relaciones claras; usa una cadena solo para texto plano
Referencia a camposDot path con backticks: `ticket.messages[0].text`Escríbelo en las instructions de la pregunta
Límites del contenidoEl material y los hechos de apoyo van en state, los juicios van en questionsCambiar de pregunta sin tocar el state
Contexto64k por solicitud / 32k por preguntaEl header de contexto largo es el último recurso, «más lento y menos preciso»
Identificar camposUsa cadenas para IDs y números grandesAcepta solo valores finitos para los números
RecorteEnvía solo los campos que necesita cada preguntaFiltra primero en código: ahorra tokens y protege la precisión

Vista previa de la próxima lección ​

Con el material listo, en la próxima lección aprenderás la primera forma de preguntar: Choice, preguntas de opción múltiple: elegir una de entre opciones fijas y obtener la opción elegida, la probabilidad de cada opción y la confianza.

Aprenderás:

  • Definir el map de opciones con criteria, de modo que la respuesta siempre caiga dentro de las opciones que das
  • Interpretar los tres campos de retorno choice / probabilities / confidence y usarlos directamente para dirigir las ramificaciones del código
  • Por qué usar Choice en lugar de dejar que el modelo improvise cuando «la respuesta es un conjunto de opciones conocidas»
  • El orden de las opciones también influye en la respuesta: cómo autoverificarte con «reordenar las opciones para comprobar la consistencia»
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.