Skip to content

Puntuación compuesta: divide un juicio complejo en puntuaciones atómicas y pondera ​

El enrutamiento inteligente de la lección anterior usaba un Score para evaluar la complejidad y respondía a la pregunta «¿me atrevo a ejecutar automáticamente esta respuesta?». Esta lección responde a otra pregunta: tienes un lote de cosas delante y quieres elegir las mejores X según varios criterios —el filtrado de currículums, la clasificación de tickets y la reordenación de búsquedas son todos de este tipo.

El equipo oficial le puso nombre: Composite scoring (puntuación compuesta). El método en una frase: divide el juicio complejo en dimensiones independientes, puntúa cada dimensión con su propio Score y combina con pesos que controlas en el código. El caso de la página oficial de patrones es el filtrado de currículums para un puesto de ingeniería: 4 dimensiones, una solicitud, dos conjuntos de pesos, dos clasificaciones. Todo en 10 minutos.

En realidad ya escribiste su versión mínima: en el paso 5 de la lección de Score se calculaba la prioridad de un ticket 0.66 con tres preguntas. Esta lección amplía esas tres líneas de ponderación a un sistema completo de ordenación —múltiples candidatos, múltiples roles, más un método de depuración para «qué hacer cuando la clasificación no es la esperada».

Qué podrás hacer al terminar ​

  • Usar la puntuación compuesta de Jev para descomponer juicios multidimensionales del tipo «¿es bueno este candidato?»: cuatro dimensiones, cada una con un Score atómico, y recuperar puntuaciones independientes en paralelo con una sola solicitud
  • Escribir el código de fusión normalizada y ponderada: cada pregunta se divide por el nivel máximo para llevarla a 0–1 y luego se suma según los pesos —el scoring.py oficial sirve tal cual
  • Servir a dos roles con el mismo lote de puntuaciones atómicas: pesos de Senior IC 0.40/0.10/0.40/0.10, pesos de Engineering Manager 0.15/0.40/0.20/0.25, una sola ronda de puntuación para dos clasificaciones
  • Si la clasificación no es la esperada, cambiar solo las constantes de peso y recalcular localmente, sin tocar la escala ni el prompt; para añadir una dimensión, agregar una pregunta al diccionario de preguntas sin que cambie el número de solicitudes por candidato
  • Explicar la división de tareas entre la puntuación compuesta y el gate de la lección anterior: el gate decide «si se puede usar», la puntuación compuesta decide «cómo ordenar»

Tu problema actual ​

  • Pido al modelo que filtre currículums y en el prompt escribo «evalúa con una puntuación de 1–10 combinando profundidad técnica, liderazgo de equipo, arquitectura y amplitud». Me devuelve un ensayito con un 7.5; al repetirlo al mes siguiente sale 8.2 —sin distribución, sin justificación. Cuando el gerente de contratación pregunta «¿cómo se calculó este 7.5?», solo puedo leerle el ensayito
  • Si la ordenación sale mal, solo puedo cambiar el prompt: añado una frase de «dar más importancia a la capacidad de arquitectura», vuelvo a ejecutar los 200 currículums y la clasificación del grupo con profundidad técnica también se desordena. No puedo decir si influyó la redacción o si el modelo estaba distinto esta vez
  • Los puestos de Senior IC y de Engineering Manager buscan dos perfiles distintos; escribí dos prompts y ejecuté cada uno —el mismo candidato difiere en más de diez puestos entre las dos listas, y además las dos puntuaciones no tienen ninguna comparabilidad

Cuándo usar esta técnica ​

Cuando necesitas:

  • Ordenar un lote de cosas según varios criterios y quedarte con los X primeros: filtrado de currículums, prioridad de tickets, clasificación de calidad de contenido, reordenación de resultados de búsqueda
  • Que los criterios de ordenación cambian a menudo, o que distintos puestos y escenarios tienen énfasis distintos: cambiar los pesos cambia la lista, sin reenviar solicitudes
  • Que la puntuación total se pueda descomponer y explicar: cuánto aporta cada dimensión, cuánto pesa cada una, todo a la vista en el código

Y además no quieres:

  • Parsear el texto de «puntuación global» que devuelve el LLM y escribir un montón de código de respaldo por el desplazamiento de formato
  • Cambiar el prompt y reejecutar todo cada vez que ajustas un criterio, con resultados que además no son reproducibles
  • Ejecutar el modelo una vez por rol para el mismo lote de candidatos

🎒 Preparativos antes de empezar ​

  • Haber leído Flujos de trabajo eficientes: cuatro patrones de arquitectura y saber dónde encaja la puntuación compuesta entre los cuatro patrones oficiales (beneficios indicados: coste, fiabilidad, velocidad)
  • Saber escribir preguntas de puntuación Score: toda esta lección se construye sobre eso —cómo redactar la escala y por qué la puntuación puede caer entre dos niveles se explicó en los pasos 1 y 3 de esa lección; el ejemplo de prioridad con tres preguntas del paso 5 es la versión mínima de esta lección
  • Haber completado la primera solicitud: .venv tiene instalado typesafe-sdk y TYPESAFE_API_KEY ya está en las variables de entorno
  • Recordar la conclusión de preguntas en paralelo: varias preguntas evalúan el mismo state en paralelo y de forma independiente, y añadir preguntas casi no aumenta el tiempo de respuesta (gracias a esto esta lección recupera las 4 preguntas de una sola vez)

Idea central ​

Primero dividir, luego combinar. Definición oficial de Composite scoring, textual:

Break a complex judgment into atomic scores, combine with weights you control in code. (Divide un juicio complejo en puntuaciones atómicas y combínalas con pesos que controlas en el código.)

¿Cuándo se usa? La introducción oficial: a menudo necesitamos ordenar un lote de cosas según varios criterios. La puntuación compuesta es la forma más simple de descomponer esa tarea —el juicio se divide en dimensiones independientes, cada dimensión se puntúa por separado y se combinan ponderadamente en el código.

La página oficial de patrones usa el filtrado de currículums como demostración completa (contratación de un puesto de ingeniería; al final, los X primeros pasan a una revisión manual), y todo el pipeline es así:

text
candidate resume (currículum del candidato)
   │  Una solicitud: currículum + 4 preguntas Score
   ▼
┌──────────────────────────────────────┐
│ python_depth    (profundidad en Python)   │ ← 4 preguntas en paralelo, evaluación independiente
│ team_leadership (liderazgo de equipo)     │
│ system_design   (diseño de sistemas)      │
│ generalist      (grado de generalista)    │
└──────────────────────────────────────┘
   │  Una respuesta: 4 puntuaciones atómicas en 0–4
   ▼
Normalizado a 0–1 (cada pregunta ÷ 4, se hace en tu código)
   ├─ Peso de IC Senior: 40% Python + 10% liderazgo de equipo + 40% diseño + 10% generalista → ic_score
   └─ Peso de EM:      15% Python + 40% liderazgo de equipo + 20% diseño + 25% generalista → em_score
   ▼
Se ordena por puntuación total y se toman los X primeros de cada rol

¿Por qué no usar una sola pregunta grande para preguntarle al LLM «qué tan buena es esta persona en general»?

Dimensión de comparaciónPuntuación integral con prompt de LLMJev puntuación compuesta
Formato de retornoUn pequeño ensayo con un 7.5, formato aleatorioUn score tipado por dimensión (0–4) + probabilities + confidence
Múltiples criteriosTodos apretados en una puntuación integralUna pregunta y una puntuación independiente por criterio
Ajustar los criterios de ordenaciónCambiar la redacción del prompt, reejecutar todo, no reproducibleCambiar las constantes de peso en el código, recalcular al instante
Ordenación multi-rolUn conjunto de prompts por rol y ejecutar de nuevoEl mismo lote de puntuaciones atómicas, con nuevos pesos sale un nuevo ranking
Explicabilidad«El modelo cree que es bueno»Puntuación por dimensión + pesos, todo visible en el código

El manual oficial de how-to enumera «descomponer la pregunta» como el concepto más importante de toda la guía: una pregunta amplia esconde varios juicios detrás de una sola respuesta; las preguntas atómicas exponen los juicios, para que puedas verificarlos, ajustarlos y combinarlos en el código (docs/concepts/how-to-build-with-system-one.md:108).

Relación con las dos lecciones anteriores: preguntas en paralelo es la capa de transporte: 4 preguntas se obtienen con una sola solicitud; el gating del enrutado inteligente responde «¿me atrevo a usar esta respuesta?»; la puntuación combinada responde «cómo ordenar este lote de cosas». En la tabla oficial de patrones, su beneficio está anotado como Cost, Reliability, Speed, el único de los cuatro patrones que reúne los tres (docs/patterns.md:19).

Hazlo conmigo ​

Paso 1: descomponer «buen candidato» en cuatro preguntas atómicas de Score ​

Por qué: «¿es bueno este candidato?» son varios juicios superpuestos: dominio de Python, liderazgo de equipo, diseño de sistemas, amplitud de conocimientos. Si se aprietan en una sola pregunta, no puedes saber qué dimensión bajó la puntuación ni ajustar solo una dimensión. Descomponer es la premisa de todo lo que sigue.

Estas son las cuatro definiciones de preguntas que da el Playground de la página oficial del patrón (extraídas de la página renderizada; instructions y criteria son texto oficial original):

python
from typesafe_sdk import Score

RESUME_QUESTIONS = {
    "python_depth": Score(
        instructions="How much depth of python experience does this candidate have, based on the supplied resume?",
        criteria=[
            "No Python experience mentioned",
            "Mentioned but no detail",
            "Used in projects, some specifics",
            "Primary language, multiple projects",
            "Deep expertise: architecture, performance, libraries",
        ],
    ),
    "team_leadership": Score(
        instructions="How much experience does this candidate have managing or leading engineering teams?",
        criteria=[
            "No management experience mentioned",
            "Informal mentorship or tech lead role",
            "Led a small team or project",
            "Managed a team with direct reports",
            "Managed multiple teams or an engineering org",
        ],
    ),
    "system_design": Score(
        instructions="How much experience does this candidate have designing large-scale or distributed systems?",
        criteria=[
            "No architecture work mentioned",
            "Contributed to design discussions",
            "Designed components of a larger system",
            "Owned architecture of a significant system",
            "Designed systems at scale across multiple domains",
        ],
    ),
    "generalist": Score(
        instructions="How much evidence is there that this candidate picks up unfamiliar tools, roles, or domains outside their core specialty?",
        criteria=[
            "Only one domain or role mentioned",
            "Some variety but within a narrow field",
            "Worked across a few different areas or tech stacks",
            "Regularly moved between domains, wore many hats",
            "Track record of ramping up in unfamiliar areas and delivering",
        ],
    ),
}

Tres detalles:

  • Una dimensión por pregunta. «Una pregunta que mide varias cosas» es el pozo señalado en la lección de Score: si la descripción de niveles se escribe como «puntual, inteligente, con experiencia», una entrada alta en un aspecto y baja en otro no tiene dónde colocarse, el confidence baja y el significado de la puntuación se enturbia. Las cuatro preguntas quedan bien separadas, cada una se ocupa de una sola cosa
  • Cada nivel es una situación, no un grado. «Primary language, multiple projects» se puede cotejar con el currículum; «dominio bastante bueno» no: el modelo solo usa la descripción para cotejar con el state; ni el número del nivel ni sus vecinos son visibles para él. La lección de Score hizo un experimento: una escala numérica pura dio un confidence de 0.33; una escala de descripciones situacionales dio 1.0
  • Número de niveles = cuántos escalones sabes describir con claridad. Aquí lo oficial usa 5 niveles por pregunta; el principio de la lección de Score es usar tantos niveles como puedas describir, como máximo 10, y 3 también vale: no añadas niveles que no puedas describir con claridad

Deberías ver: en RESUME_QUESTIONS hay cuatro Score, cada uno mide una sola dimensión y lleva su escala situacional de 5 niveles: profundidad en Python, liderazgo de equipo, diseño de sistemas, generalista, sin mezclarse entre sí. Los ID de las preguntas (python_depth y demás) los eliges tú, no se envían al modelo, y las respuestas vuelven con el mismo ID.

  • Cada una de mis preguntas mide una sola dimensión, y cada nivel es una descripción situacional cotejable

Paso 2: obtener en paralelo las cuatro puntuaciones atómicas con una sola solicitud ​

Por qué: las cuatro dimensiones son independientes entre sí; como se dijo en la lección anterior, las preguntas independientes deben agruparse en una sola solicitud: la evaluación en paralelo casi no aumenta el tiempo de respuesta y solo cuesta unos tokens más de preguntas. Cuatro preguntas separadas sin pagar el precio de cuatro solicitudes: de ahí viene el beneficio de «costo» de la puntuación combinada.

Crea resume_screen.py, conecta las definiciones de preguntas del paso 1 y prueba con un currículum:

python
from typesafe_sdk import TypeSafeClient

# RESUME_QUESTIONS 的定义见第 1 步,此处省略

resume = """
Jane Doe — Backend Engineer, 8 years
- Primary language Python; built and own the retry and backoff layer
  of a 40-node distributed ingestion pipeline (2M events/day)
- Tech lead of a 4-person payments squad for 2 years; no direct reports
- Contributed to architecture reviews across the org
- Backend infrastructure only; one year on an internal CLI tool
"""

with TypeSafeClient() as client:
    response = client.system_one(
        state=resume,
        questions=RESUME_QUESTIONS,
    )

for qid in ["python_depth", "team_leadership", "system_design", "generalist"]:
    answer = response.answers[qid]
    print(qid, answer.score, answer.confidence)

Ejecútalo:

bash
.venv/bin/python resume_screen.py

(El ejemplo del Playground oficial solo incluye 4 preguntas y no da un state de currículum; el texto de este currículum es una entrada de prueba creada para esta lección.)

Deberías ver: un número entre 0–4 para cada uno de los cuatro, cada uno con su confidence de 0–1. Léelo contra este currículum inventado: Python es el lenguaje principal y aparece en varios proyectos → python_depth alto; tech lead sin direct reports → team_leadership queda en medio; solo participó en discusiones de arquitectura → system_design medio-bajo; casi solo backend → generalist bajo. La puntuación puede caer entre dos niveles (por ejemplo 1.5): es la posición media ponderada por probabilidades; el método de verificación está en la lección de Score, paso 3. Los valores concretos dependen de tu respuesta real y pueden variar según la versión de Jev.

Observación clave: las cuatro dimensiones son independientes; un candidato perfectamente puede tener Python 3.8 y liderazgo de equipo 0.5. En una pregunta integral estas dos señales se diluirían mutuamente; separadas, cada una queda clara.

💡 Los currículums en chino también se pueden puntuar, pero calibra primero

La documentación oficial indica que el inglés es el principal lenguaje de entrenamiento y el de mejor precisión; otros idiomas, incluido el chino, funcionan pero con menor precisión (docs/models.md). Antes de poner en producción currículums en chino, corre primero un lote de currículums calificados manualmente y fíjate sobre todo en la distribución del confidence por dimensión: el nivel que no se separe bien en chino, complétale las descripciones situacionales.

  • Un currículum claro obtiene puntuación en las cuatro dimensiones; cambia a un currículum con otro enfoque y las puntuaciones de cada dimensión cambian de forma independiente

Paso 3: escribir el código de fusión ponderada de la puntuación combinada de Jev ​

Por qué: con las puntuaciones atómicas en la mano, la regla de fusión debe escribirse en el código y no en el prompt: de ahí viene toda la explicabilidad del patrón. Cómo se calcula la puntuación total, cada término queda a la vista.

El scoring.py de la página oficial del patrón, tal cual:

python
py      = response.answers["python_depth"].score / 4
lead    = response.answers["team_leadership"].score / 4
arch    = response.answers["system_design"].score / 4
general = response.answers["generalist"].score / 4

# Senior IC
ic_score = (0.40 * py) + (0.10 * lead) + (0.40 * arch) + (0.10 * general)

# Engineering Manager
em_score = (0.15 * py) + (0.40 * lead) + (0.20 * arch) + (0.25 * general)

Tres lecturas:

  • / 4 es la normalización. Cada pregunta tiene 5 niveles, el número máximo es 4, y tras dividir todo cae en 0–1. La forma general es «dividir por el número máximo de niveles len(criteria) - 1»: el normalized() del paso 5 de la lección de Score es esa forma general. Las cuatro preguntas de esta lección tienen el mismo número de niveles y parecería que puedes ahorrarte la división, pero lo oficial divide igual: escribe la normalización de forma uniforme, y si algún día la escala de una dimensión se alarga o se acorta, el código de fusión no tiene que cambiar
  • Los pesos son la postura del producto. Senior IC: profundidad en Python y diseño de sistemas 0.40 cada uno, liderar equipo solo 0.10; Engineering Manager: liderar equipo 0.40 domina por sí solo. La suma de ambos conjuntos de pesos es 1.00, por lo que la puntuación total sigue cayendo en 0–1, y las dos listas pueden compararse directamente entre sí
DimensiónSenior ICEngineering Manager
python_depth0.400.15
team_leadership0.100.40
system_design0.400.20
generalist0.100.25
  • Primero normaliza y luego pondera; el orden no se puede invertir. El significado de los pesos se construye sobre la escala 0–1: 0.40 de Python es exactamente el doble de 0.20 de diseño de sistemas — cuando las puntuaciones no están normalizadas, esa afirmación no se cumple

Deberías ver: ic_score y em_score son cada uno un número entre 0–1. Para el currículum del paso 2, la puntuación total de IC debería ser mayor que la de EM — ese currículum es fuerte en Python y débil en liderazgo de equipo, y liderar equipo en los pesos de EM ocupa por sí solo 0.40.

  • Mi código de fusión primero normaliza (÷ número de nivel más alto) y luego multiplica por los pesos; cada conjunto de pesos suma 1.00

Paso 4: el mismo lote de puntuaciones atómicas, dos listas con dos conjuntos de pesos ​

Por qué: lo más elegante de este ejemplo oficial está en «una sola ronda de puntuación, reutilización para múltiples roles»: las puntuaciones de las cuatro dimensiones valen para cualquier puesto; lo único que cambia son los pesos. Si metes los pesos en un diccionario y escribes la fusión como función, tienes una herramienta capaz de ordenar para cualquier rol — y las puntuaciones atómicas se obtienen una sola vez por candidato.

python
WEIGHTS = {
    "senior_ic": {
        "python_depth": 0.40, "team_leadership": 0.10,
        "system_design": 0.40, "generalist": 0.10,
    },
    "eng_manager": {
        "python_depth": 0.15, "team_leadership": 0.40,
        "system_design": 0.20, "generalist": 0.25,
    },
}


def composite(answers, weights: dict) -> float:
    """归一化后按权重合并;算式与官方 scoring.py 一致。"""
    total = 0.0
    for question_id, weight in weights.items():
        top_level = len(RESUME_QUESTIONS[question_id].criteria) - 1
        total += weight * answers[question_id].score / top_level
    return total


def fetch_scores(resumes: dict) -> dict:
    """每个候选人一次请求,拿回四个原子分数。"""
    raw = {}
    with TypeSafeClient() as client:
        for name, resume in resumes.items():
            response = client.system_one(state=resume, questions=RESUME_QUESTIONS)
            raw[name] = response.answers
    return raw


CANDIDATES = {
    "jane": resume,  # 第 2 步那份简历;再放两三份不同侧重的简历
    # "li": ...,
    # "sam": ...,
}

raw = fetch_scores(CANDIDATES)

ic_rank = sorted(raw, key=lambda n: composite(raw[n], WEIGHTS["senior_ic"]), reverse=True)
em_rank = sorted(raw, key=lambda n: composite(raw[n], WEIGHTS["eng_manager"]), reverse=True)

print("Senior IC 榜:", ic_rank)
print("EM 榜:", em_rank)

(La fórmula de fusión coincide punto por punto con la oficial scoring.py; el bucle fetch_scores y la ordenación son Python común añadidos por esta lección. Un request por candidato, 4 preguntas en paralelo — el mismo ritmo que el RAG cookbook oficial con «un request por fragmento».)

Deberías ver: las dos listas provienen del mismo lote de puntuaciones atómicas — fetch_scores se ejecutó una sola vez; el segundo rol, EM, no generó ninguna llamada nueva a la API. Si un candidato tiene Python muy profundo pero nunca ha liderado personas, aparecerá en los primeros puestos de la lista IC y en los últimos de la lista EM; un candidato con experiencia sólida de liderazgo es justo lo contrario. Esto es algo que ejecutar cada prompt dos veces por separado jamás te dará: las dos listas se basan en el mismo conjunto de mediciones, y las diferencias provienen solo de los pesos.

  • Mi segundo rol (EM) no disparó una segunda petición — las puntuaciones se tomaron del mismo lote de respuestas

Paso 5: cuando el ranking no es el esperado, cambia solo los pesos, no toques el prompt ​

Por qué: el resumen oficial de este código tiene dos capas: te permite ordenar por puntuación total, «pero lo más importante es que te deja ver cómo se calcula exactamente esa puntuación total»; cuando el candidato mejor clasificado no coincide con lo esperado, «puedes ajustar los pesos para encontrar el equilibrio adecuado». Los pesos son tuyos — esta frase literal (The weights are yours) aparece una vez en la documentación oficial de primitives y otra en la de Score: cuando el resultado combinado no coincide con los criterios de tu equipo, cambia los pesos del código y vuelve a ejecutar.

Recorre una vez el escenario de depuración. El manager contratante mira la lista IC: «quienes han liderado equipos quedan demasiado abajo».

python
# 改权重前:python 0.40 / lead 0.10 / arch 0.40 / general 0.10
WEIGHTS["senior_ic"] = {
    "python_depth": 0.35, "team_leadership": 0.20,
    "system_design": 0.35, "generalist": 0.10,
}

# 原子分数已经在 raw 里,直接重算——不用再发任何请求
ic_rank = sorted(raw, key=lambda n: composite(raw[n], WEIGHTS["senior_ic"]), reverse=True)

Tres ajustes, prueba del costo más bajo al más alto:

AjusteCostoAlcance del impacto
Cambiar las constantes de pesosCero llamadas a la API (las puntuaciones ya están, se recalcula localmente)Solo afecta a esta lista
Añadir una dimensión (p. ej. comunicación)Reejecutar un request por candidato — pero cada candidato sigue siendo un solo request; palabras oficiales: «The call count stays at one»Todas las listas que usan este conjunto de puntuaciones comparten la nueva dimensión
Cambiar la redacción de la escala (criteria)Reejecutar para todos los candidatos; las puntuaciones nuevas y viejas no son comparablesTodas las puntuaciones existentes quedan invalidadas

Deberías ver: tras cambiar los pesos, ic_rank recalcula de inmediato una lista nueva — no cambió ni un número en raw, porque las preguntas no se movieron ni una palabra. Esto es «cambiar los coeficientes sin cambiar el prompt»: reproducible, auditable, reversible (vuelve a poner los pesos como estaban y la lista vuelve a la anterior).

  • Considero «cambiar los pesos» como el primer recurso para depurar rankings, y dejar la redacción de la escala para el final

Punto de control ✅ ​

  • Puedo explicar los dos pasos de la puntuación compuesta de Jev: una pregunta Score atómica por dimensión, con todas las puntuaciones obtenidas en paralelo en una sola solicitud; en el código, normalizar y luego fusionar ponderando
  • Sé por qué se normaliza primero: las escalas distintas tienen máximos distintos (escala de tres niveles con máximo 2, escala de cinco niveles con máximo 4); solo dividiendo por el número de nivel más alto len(criteria) - 1 quedan en la misma escala, y solo entonces los pesos expresan lo que dicen literalmente
  • Mis pesos son constantes del código y suman 1.00; si el ranking no es el esperado, primero cambio los pesos y recalculo localmente, sin enviar nuevas peticiones
  • Con el mismo lote de puntuaciones atómicas construí las dos listas, IC y EM; el segundo rol supuso cero llamadas adicionales a la API
  • Al ordenar miro también el confidence de cada dimensión: los candidatos de baja confianza se marcan para revisión, en lugar de ordenarlos a la fuerza

Advertencia de errores comunes ​

❌ Una sola pregunta que pregunta «qué tal en general» ​

El prompt dice «evalúa de forma integral a este candidato y dale una nota de 1–10»: varios juicios apretados en una sola respuesta. El manual oficial how-to lo señala como el concepto más importante de toda la guía:

Las preguntas amplias esconden varios juicios detrás de una sola respuesta; las preguntas atómicas exponen esos juicios, y solo así puedes inspeccionarlos, ajustarlos y fusionarlos en el código.

Con una pregunta integral no puedes saber qué dimensión bajó la nota, ni ajustar una sola dimensión. La forma correcta: un Score por dimensión — las cuatro preguntas del paso 1 de esta lección son el paradigma.

❌ Ponderar sin normalizar primero ​

La escala de tres niveles tiene máximo 2 y la de cinco niveles máximo 4 — sin normalizar, la dimensión con más niveles sale beneficiada por naturaleza, y el 0.40 que escribiste puede tener en la práctica un efecto mucho mayor que 0.40. La documentación oficial de Score lo subraya expresamente: dividir primero por el número de nivel más alto antes de fusionar, «para que los pesos signifiquen lo que dicen» (Then the weights mean what they say) — el severity de 0.6 es exactamente el doble del frustration de 0.3. Las cuatro preguntas de esta lección comparten nivel, y / 4 parece superfluo, pero la documentación oficial lo escribe igualmente — lo que previene es que en el futuro la escala se alargue o se acorte.

❌ Si el ranking sale mal, ir a cambiar la redacción de la escala ​

En cuanto cambias la escala, cambia el significado de las puntuaciones: las puntuaciones antiguas de todos los candidatos quedan invalidadas, hay que reejecutar todo, y las listas nuevas y viejas no se pueden comparar directamente. La acción que da la documentación oficial es «cambiar los pesos del código y reejecutar» — costo cero, verificable al instante, afecta solo a una lista (la tabla de costos del paso 5). La redacción es el último recurso: solo cuando el confidence de una dimensión es sistemáticamente bajo (los niveles no se separan con tus datos reales) conviene volver y cambiar la escala, y validar la nueva escala con muestras conocidas según el método de la lección Score.

❌ Mirar solo la puntuación total e ignorar el confidence de cada dimensión ​

La puntuación total comprime las cuatro dimensiones en un solo número, y las puntuaciones de dimensiones con baja confianza quedan mezcladas sin poder distinguirse. Si la confidence de system_design de un candidato es solo 0.3 (niveles superpuestos, o información insuficiente en el currículum), su puntuación total se calcula igualmente, pero usar esa puntuación total para decidir si pasa a la entrevista se basa en un criterio poco fiable. El uso oficial de los tres niveles de confidence también se aplica a la ordenación: alta → usar directamente; media → marcar para revisión; baja → no permitir que esa dimensión participe en la decisión y pasar a revisión manual. La interpretación completa de los tres niveles está en la lección Confidence 置信度.

Técnicas avanzadas (opcional) ​

La fusión ponderada no se limita a Score. El ejemplo de la sección 7 del manual oficial how-to usa la ponderación probabilística de tres Noul para sintetizar una puntuación de calidad: Noul ya es de por sí una probabilidad en 0–1, así que hasta la normalización se ahorra:

python
answers = response.answers

# Combine independent signals into one application-specific score.
quality = (
    0.4 * answers["answers_request"].noul
    + 0.4 * answers["citations_are_supported"].noul
    + 0.2 * (1 - answers["contradicts_context"].noul)
)

(Código oficial tal cual, docs/concepts/how-to-build-with-system-one.md. Nótese que la tercera señal toma 1 - noul: cuanto menor es la probabilidad de contradecir el contexto, mayor es la puntuación de calidad.)

Dejar que la máquina aprenda los pesos. Los pesos no tienen por qué ajustarse a mano para siempre. El mismo pasaje de la documentación oficial ofrece una vía avanzada: usar las probabilities de cada pregunta como características y alimentar con ellas un modelo clásico de aprendizaje automático aguas abajo para que aprenda la forma de combinarlas; cuando no hay etiquetas, se puede usar un conjunto de modelos de inferencia costosos como ensemble para generarlas. El cookbook oficial AutoResearch (autoresearch_feature_discovery, todavía sin página propia) demuestra el método completo: el bucle autoresearch propone preguntas TypeSafe, convierte el texto libre en características numéricas, entrena un regresor CatBoost y luego usa el error del modelo para mejorar las preguntas a la inversa.

Combinación de señales en escenarios reales. La idea de «múltiples señales, fusión en el código» aparece por todas partes en las lecciones prácticas:

  • Filtro de pasajes RAG: a cada pasaje recuperado se le hacen 4 preguntas Noul (¿es relevante?, ¿contiene evidencia?, ¿contradice las premisas?, ¿hay inyección?), y el código decide cuáles entran en el contexto del answering model. La documentación oficial señala expresamente que ninguna de las cuatro preguntas pregunta «¿se debe incluir este pasaje?» — esa decisión está en el código, y cambiar el criterio es cambiar un número, sin reescribir las preguntas
  • Búsqueda y matching: el reranking es la forma de ordenación pura — una pregunta Noul por cada par consulta-candidato, ordenadas por probabilidad; las pruebas oficiales muestran que top-1 pasa de 5% a 18% de aciertos; la alineación de entidades, en cambio, es un juicio combinado de 1 Score más 3 Noul

Resumen de la lección ​

✅ Jev: la puntuación compuesta = el patrón oficial Composite scoring: se descompone un juicio complejo en una pregunta Score atómica por dimensión, se obtienen todas en paralelo en una sola solicitud, y en el código se normalizan y fusionan con pesos — el beneficio oficial indicado es Cost, Reliability, Speed, el único de los cuatro patrones que reúne los tres.

✅ Los pesos son decisiones de producto: Senior IC 0.40/0.10/0.40/0.10, Engineering Manager 0.15/0.40/0.20/0.25 — las mismas puntuaciones atómicas, dos conjuntos de pesos, dos rankings, y el segundo rol sin peticiones adicionales.

✅ La explicabilidad es el mayor beneficio: cómo se calcula la puntuación total, las puntuaciones y los pesos de cada dimensión son totalmente visibles en el código; si un ranking no es el esperado, primero se cambian los pesos y se recalcula localmente, reproducible y reversible.

✅ Añadir dimensiones no añade peticiones: se agrega una pregunta al diccionario de preguntas y el número de llamadas por candidato sigue siendo 1 — palabras textuales oficiales: «The call count stays at one».

Consulta rápida de datos clave:

ElementoValorFuente
El patrón en una fraseCombine several dimensions of analysis into a single scoredocs/patterns.md
Definición del patrónBreak a complex judgment into atomic scores, combine with weights you control in codedocs/patterns/composite-scoring.md
Las cuatro preguntaspython_depth / team_leadership / system_design / generalist, cada una con una escala de 5 nivelesPlayground oficial (patterns/composite-scoring, extraído de la página renderizada)
Normalizaciónscore ÷ (len(criteria) − 1), en este ejemplo cada pregunta ÷ 4docs/primitives/score.md
Pesos ICPython 0.40 / liderar equipo 0.10 / diseño 0.40 / generalista 0.10docs/patterns/composite-scoring.md (scoring.py)
Pesos EMPython 0.15 / liderar equipo 0.40 / diseño 0.20 / generalista 0.25ídem
BeneficioCost, Reliability, Speeddocs/patterns.md

La puntuación combinada es un patrón de la capa «cómo usar las respuestas»; antes de ponerla en producción hay que repasar igualmente los nueve modos de fallo de Jev 1.13 el manual de trampas — en especial el de «interpretación literal»: en las descripciones de las escalas escribe condiciones precisas, no palabras de grado como «tiene una buena capacidad de arquitectura».

Avance de la próxima lección ​

Con esta lección se han repasado los cuatro patrones oficiales (fan-out, enrutado por intención, gating por confianza, puntuación combinada); queda una última pregunta: quién escribe el código que llama a Jev. Próxima lección desarrollo conjunto con Claude Code: TypeSafe Agent Skill.

Aprenderás:

  • Jev no es el LLM del coding agent: no puede sustituir al modelo detrás de Claude Code / Cursor; el enfoque correcto es dejar que el agent escriba «el código que llama a Jev»
  • Dos comandos para instalar el Agent Skill oficial: claude plugin marketplace add typesafe-ai/skills, luego claude plugin install typesafe@typesafe-ai
  • 3 prompts de ejemplo oficiales: lluvia de ideas, ejecutar experimentos baratos, buscar cookbooks similares
  • 5 métodos de diagnóstico para problemas frecuentes: el agent no usa el skill, el enrutado no coincide con lo esperado, establecer umbrales de confidence por todas partes, código difícil de revisar, el agent inventa campos
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.