Migrar desde Jev

Sonoe implementa la misma API HTTP que Jev de TypeSafe: el mismo endpoint, las mismas preguntas y las mismas respuestas. El código escrito para Jev pasa a Sonoe cambiando dos ajustes.

En corto

export TYPESAFE_BASE_URL="https://api.sonoeai.com"
export TYPESAFE_API_KEY="sk_sonoe_..."   # una key de la consola de Sonoe

Eso es todo. Los SDK oficiales de TypeSafe leen las dos variables, así que mandan las mismas solicitudes a Sonoe y reciben respuestas que entienden. Los probamos contra Sonoe tal como son:

Si llamas a la API HTTP directamente, cambia el host de api.typesafe.ai a api.sonoeai.com y la key. La ruta (POST /v1/systemone), el cuerpo y las respuestas se quedan igual.

Nombres de modelo

No tienes que cambiar el campo model. Sonoe acepta los nombres de Jev como alias de su modelo actual:

El campo model de la respuesta dice qué contestó de verdad: sonoe-1.1.0. Cualquier otro nombre devuelve 404. Cuando quieras, define TYPESAFE_DEFAULT_MODEL=sonoe-latest (o defaultModel en el cliente de JS) para que tus registros digan lo que significan.

Lo que se queda igual

• POST /v1/systemone con state, model y questions; GET /v1/models devuelve { "models": [...] }.
• Authorization: Bearer <key>.
• Preguntas Noul, Choice y Score, con instructions y criteria como texto, objetos o listas.
• Respuestas: noul; choice + probabilities + confidence; score + legend + probabilities + confidence. Vuelven bajo los ids de pregunta que elegiste.
• usage.input_tokens y usage.output_tokens.
• Cuerpos comprimidos con Content-Encoding: zstd (lo que mandan los SDK desde 1 KiB) o gzip.
• Un encabezado x-typesafe-request-id en cada respuesta.
• Códigos de estado: 401 por una key mala, 422 por una pregunta inválida (con la ruta del campo), 429 cuando pasas un límite, con Retry-After para que los SDK esperen lo justo.

Lo que cambia

Detalles más pequeños:

• Se aceptan instructions ausentes o en null: un Noul usa entonces sus criteria; un Choice o un Score preguntan qué opción o nivel encaja mejor.
• criteria.true y criteria.false de un Noul se leen como parte de la pregunta («Yes means: …», «No means: …»).
• Los campos desconocidos del nivel superior se ignoran.

Comprueba la precisión con tus datos

Sonoe 1.1 es un modelo multilingüe pequeño (un cross-encoder de 118M de parámetros basado en multilingual-e5-small). Es rápido y está calibrado, pero es sensible a la redacción de maneras en que un modelo más grande no lo es. Por ejemplo, con el estado «I was charged twice. Please help ASAP.»:

• «Is this about billing?» sacó una probabilidad baja, muy por debajo de 0.5.
• «Is this about a payment or a charge?» sacó cerca de 0.97.

Así que, antes de cambiar:

1. Toma unos cientos de solicitudes reales de las que ya sepas la respuesta correcta.
2. Mándalas a Sonoe (solo cambia la URL base) y compáralas con tus etiquetas y con Jev.
3. Donde Sonoe se equivoque, prueba palabras más simples en instructions y dale a cada opción de Choice una descripción corta en criteria en vez de null.
4. Mira la confidence de los errores: muchas veces puedes mandar las respuestas de confianza baja a una persona o a otra regla en vez de confiar en ellas.

Lista de pasos

• Crea una cuenta y una key en sonoeai.com.
• Define TYPESAFE_BASE_URL=https://api.sonoeai.com y TYPESAFE_API_KEY=sk_sonoe_… (o cambia el host y la key en tu cliente HTTP).
• Quita las imágenes y las preguntas Box, o deja esas solicitudes en Jev.
• Mantén cada estado corto: Sonoe lee hasta 256 tokens por opción.
• Mantén los cuerpos por debajo de 64 KiB y las solicitudes por debajo de 64 preguntas.
• Compara la precisión con tus propios datos etiquetados.
• Revisa tu cuota y tu límite por minuto en Errores y límites.
• Si quieres, cambia el modelo predeterminado a sonoe-latest.