Ir al contenido
Base de conocimiento

Herramientas de paquetes — Referencia de herramientas MCP

Un paquete vincula un proyecto, un cuestionario y un subconjunto no vacío de las campañas de ese cuestionario con exactamente una cadena lineal de conjuntos de datos Bronce → Plata → Oro. Estas herramientas gestionan el propio paquete y su resumen de calidad; consulte Herramientas de conjuntos de datos para las operaciones por etapa con ámbito de paquete (extracción, codificación + ponderación, refinamiento, exportación).

Crea un paquete del proceso.

Parámetro Tipo Obligatorio Predeterminado Descripción
name string Sí — Nombre del paquete
project_id string Sí — Proyecto propietario (requiere acceso de escritura)
questionnaire_id string Sí — Cuestionario cuyas encuestas completadas alimentan el conjunto de datos Bronce
campaign_ids string[] Sí — Subconjunto de campañas que se mide. Debe indicar al menos una: la base de medición de un paquete son las encuestas de las campañas que selecciona

Devuelve: { bundle_id, name }


Lista los paquetes del proceso, opcionalmente filtrados por un proyecto.

Parámetro Tipo Obligatorio Predeterminado Descripción
project_id string No — Limita el resultado a los paquetes de este proyecto

Devuelve:

{
"items": [
{
"id": "...",
"name": "Wave 1",
"project_id": "...",
"questionnaire_id": "...",
"campaign_ids": ["..."],
"chain": {
"bronze": {"dataset_id": "...", "status": "ready"},
"silver": {"dataset_id": "...", "status": "processing"}
}
}
],
"count": 1
}

Las claves de chain son las etapas que tienen un conjunto de datos (bronze/silver/gold); una etapa que todavía no tiene conjunto de datos simplemente no aparece: trátela como missing.


Copia en profundidad los conjuntos de datos listos y las recetas de un paquete en una variante independiente.

Parámetro Tipo Obligatorio Predeterminado Descripción
bundle_id string Sí — Paquete de origen
name string No "{source} (copy)" Nombre del clon

Devuelve: { bundle_id, cloned_stages }; cloned_stages indica qué etapas (bronze/silver/gold) tenían un conjunto de datos listo para copiar.

El clon parte de una copia idéntica byte a byte de cada etapa lista y lleva las mismas recetas de etapa (la selección de codificación y su libro de códigos de dimensiones, los objetivos de ponderación, las especificaciones de campos de refinamiento), de modo que puede volver a derivarse de forma independiente —por ejemplo, con otros objetivos de ponderación— sin tocar el paquete original. Así se comparan variantes (otra ponderación, otro refinamiento) de la misma extracción sin procesar.


Elimina un paquete y su cadena de conjuntos de datos.

Parámetro Tipo Obligatorio Predeterminado Descripción
bundle_id string Sí — Paquete que se elimina

Devuelve: { success: true }

La eliminación es lógica: el paquete y los conjuntos de datos de su cadena se marcan como eliminados de inmediato, y un proceso de mantenimiento en segundo plano limpia poco después los archivos de datos subyacentes.


La calidad se mide en el paquete, no en conjuntos de datos individuales. Tres de las cuatro medidas de representatividad se evalúan frente a la estrategia vigente del paquete (current_strategy_id), que puede reasignarse: asigne una antes de esperar que estén en measured. Un objetivo de calibración con raking es la instrucción de ponderación, no una referencia: evaluar el resultado ponderado frente a la especificación a la que apuntaba la ponderación haría que un raking correcto puntuara bien por construcción. Un objetivo de calibración solo de referencia es lo contrario: una cifra externa a la que la ponderación nunca apuntó, por lo que la muestra se evalúa frente a ella.

El resumen de representatividad del paquete en una sola llamada: una muestra seguida desde la intención del diseño hasta el entregable.

  1. Estrategia → Grupo (selection): ¿logró el muestreo el diseño? Por cada grupo del que se nutrieron las campañas del paquete, y agregado solo cuando coinciden en una misma estrategia. Se evalúa a partir de los valores de cada miembro registrados al seleccionar el grupo; un grupo sin un registro completo da not_measurable (pool_has_no_complete_snapshot)
  2. Estrategia → Real (fielded): ¿cuánto se desviaba la base obtenida antes de ponderar? Con un desglose por campaña; no_strategy hasta que se asigna una estrategia
  3. Estrategia → Ponderado (weighted): ¿recuperó la ponderación el diseño? Se evalúa frente a la misma estrategia que (2), de modo que ambas difieren exactamente en lo que recuperó la ponderación
  4. Grupo → Real (fielding_shift): ¿qué aportó el propio trabajo de campo? Tiene el grupo como referencia y considera solo las encuestas procedentes del grupo, de modo que responde a una pregunta distinta de (1)–(3) y no es un cuarto punto en su escala
  5. Calidad de las respuestas (response): entropía, respuestas en línea recta, alfa de Cronbach, aquiescencia, falta de respuesta (consulte la Referencia de métricas de calidad)

Junto a ellas, excluded_profile describe lo que eliminó el umbral de completitud del paquete frente a lo que conservó, comparado con los propios factores de la estrategia, porque dos recuentos de registros no pueden decir si un corte introdujo un sesgo. Un conjunto excluido vacío devuelve empty en lugar de una divergencia de cero.

Parámetro Tipo Obligatorio Predeterminado Descripción
bundle_id string Sí — UUID del paquete

Devuelve: { quality: {...} }: las cinco medidas más excluded_profile y el contexto de la cadena y la estrategia. Cada una lleva un state (measured, not_measurable, no_strategy, no_weighted_factors, empty, not_derived, processing, invalidated, error) con un reason, de modo que una medida no medible o con errores nunca oculta las demás y un cero nunca se confunde con una nota. Las cargas útiles medidas incluyen la puntuación global, el error compuesto y el análisis de desviación por factor; la carga ponderada incluye además weighting_diagnostics (efecto de diseño, tamaño efectivo de la muestra), es decir, el coste en varianza de la recuperación. fielded y weighted llevan cada una benchmarks: cada objetivo de calibración solo de referencia evaluado por categoría frente a la muestra sin ponderar y la ponderada, junto a la nota de la estrategia y nunca dentro de su compuesto; se evalúan haya o no una estrategia vigente. weighted lleva también raking_reached: la proporción ponderada de cada objetivo con raking frente a su objetivo, que muestra cuánto se acercó el raking y nunca es una nota. Una referencia sobre una columna en la que se aplicó raking al conjunto de datos Plata actual (su rol cambió después de la derivación) figura en raking_reached, no en benchmarks, dentro de weighted hasta la siguiente derivación, ya que esos pesos se ajustaron a ella. comparison_ready es true solo mientras los conjuntos de datos Bronce y Plata del paquete existen y están ambos en ready, que es exactamente cuando compare_bundle_quality responde en lugar de rechazar la llamada; un conjunto de datos Plata pendiente, fallido o invalidado sigue teniendo un id, así que lea este indicador y no los ids de los conjuntos de datos.

Un conjunto de datos Bronce extraído con una versión anterior del esquema de extracción no se evalúa: fielded, fielding_shift, response, excluded_profile y weighted dan cada uno not_measurable con el motivo bronze_schema_stale hasta que el conjunto de datos Bronce se vuelve a extraer (create_bronze_dataset) y el conjunto de datos Plata se deriva de nuevo. selection no lee ningún conjunto de datos y se sigue evaluando.


Comparación de representatividad Bronce frente a Plata para la cadena del paquete, evaluada frente a la estrategia vigente del paquete. Su campo recovery es la cifra que debe leerse: una diferencia simple del error medio ponderado sobre los factores de la estrategia medidos en ambos lados, de modo que reducciones iguales del error a niveles absolutos distintos dan cifras iguales y dos paquetes son comparables. Cuando las dos medidas no comparten ningún factor medido, es null con un recovery_reason en lugar de 0.0: no había nada comparable, lo que no equivale a que la ponderación no haya logrado nada.

Parámetro Tipo Obligatorio Predeterminado Descripción
bundle_id string Sí — UUID del paquete

Devuelve: { comparison: {...} } con recovery (la cifra global descrita arriba) y recovery_per_factor, la misma resta por factor, en unidades de error. Ambas son diferencias de error, no porcentajes: una cifra positiva significa que la ponderación redujo el error en esa cantidad. Aquí no puede expresarse con sentido un porcentaje por factor, porque su denominador sería el error del conjunto de datos Bronce, que es precisamente la magnitud que la ponderación pretende llevar a cero. Los conjuntos de datos Bronce y Plata deben estar ambos en ready; una cadena que aún no está lista falla con un error de conflicto (409 con {"error": "conflict"} en REST) y no con un error de validación: termine o vuelva a ejecutar la derivación y luego compare.

El state propio de la comparación es measured cuando se evaluaron ambos lados. Es no_strategy cuando el paquete no tiene estrategia vigente, y not_measurable con el motivo bronze_schema_stale cuando el conjunto de datos Bronce se extrajo con una versión anterior del esquema de extracción; en ambos casos, bronze, silver y recovery son null y la llamada se completa correctamente. Para salir del estado obsoleto, vuelva a extraer (create_bronze_dataset) y a derivar el conjunto de datos Plata.


El estado de codificación de respuestas abiertas del paquete: qué puede codificarse, qué preguntas eligió el analista y, para cada pregunta elegida, las dimensiones propuestas, sus categorías, cuáles están seleccionadas y si las produjo la vía degradada sin credenciales. Léalo antes de seleccionar o volver a derivar.

Parámetro Tipo Obligatorio Predeterminado Descripción
bundle_id string Sí — UUID del paquete

Devuelve: { candidates, kinds, selected, discovered, units, awaiting_review, coding_outcome, bronze_status, silver_status, pending_review }.

  • candidates: cada unidad de texto abierto que ofrece el conjunto de datos Bronce de este paquete, cada una {unit_key, title, control_type, roster_block_id, columns}. Solo cumple los requisitos Textarea, y aparecer aquí no implica nada sobre la codificación: lo que contiene la columna lo determina la clasificación del analista (kinds), y la unidad debe estar clasificada antes de poder seleccionarse. Editbox es una entrada numérica en QML (requiere un mínimo y un máximo), de modo que sus respuestas son recuentos e importes, no texto que un libro de códigos pueda describir. Un Roster es un candidato cuyas columns nombran las columnas del conjunto de datos Bronce que agrupa; una subpregunta de QuestionGroup y una celda de Matrix siguen siendo cada una su propio candidato.
  • kinds: el tipo de respuesta que el analista asignó a cada candidato, transmitido sin valores predeterminados: descriptive (prosa, codificada por significado), nominal (un vocabulario fijo, codificado por valor exacto) o identifier (nombra a una persona o un registro, nunca se codifica). Un candidato sin entrada está sin clasificar y no puede seleccionarse; null significa que no se ha clasificado nada. Aquí es de solo lectura: el analista clasifica en Balansor y ninguna herramienta escribe un tipo.
  • selected: la elección de unidades guardada, transmitida sin valores predeterminados: null significa «aún no se ha elegido» y [] significa «elegido: nada». Solo lo segundo es una decisión que alguien tomó.
  • discovered: asigna a cada unidad codificada {column: dimension label}, el registro de qué columnas emitió realmente la última derivación.
  • units: el estado de dimensiones por unidad, indexado por clave de unidad. Cada una lleva reviewed (¿alguien ha decidido qué dimensiones se convierten en columnas?), selected (los ids de dimensión elegidos, null mientras no se ha revisado y [] para «revisado, no se eligió nada»), degraded (la ronda procede de la vía sin credenciales; es lo que distingue un resultado genuino de una sola dimensión de la dimensión única de esa vía), answered / missing y dimensions. Cada dimensión lleva su id de posición, label, el nombre de column fijado, su origin (proposed / authored / degraded, o verbatim para la única dimensión de valor exacto de una unidad nominal), si está selected, sus categories como {id, label} (solo {id} para una dimensión verbatim, cuya categoría -1 es el otro reservado), los counts de asignación por columna y overlap: cuántas de las categorías propias de esa dimensión superó también una respuesta media, lo que informa sobre el libro de códigos y no sobre los encuestados.
  • awaiting_review: las unidades seleccionadas cuyas dimensiones nadie ha revisado. Esas unidades no producen ninguna columna codificada aunque la derivación se complete, por eso se nombran en lugar de inferirse.
  • coding_outcome: lo que la última derivación intentó y de lo que no obtuvo columna: {attempted, coded, lost}, cada entrada de lost {unit_key, kind}, con kind igual a not_codable, unclassified o no_column. El fallo de una unidad no hace fallar la derivación —las columnas de las demás unidades son trabajo real—, así que sin este campo la pérdida no dejaría ninguna señal: el conjunto de datos aparece como ready y discovered sigue nombrando la unidad de una derivación anterior, porque ese mapa se conserva deliberadamente entre ejecuciones. Compruébelo antes de dar por completo un conjunto de datos Plata. null significa que la derivación no registró nada, lo que no equivale a no haber perdido nada: todo conjunto de datos Plata derivado antes de que existiera este campo está en ese estado, y una lista lost vacía es el valor que indica que una ejecución no perdió nada. El motivo de una pérdida se reduce deliberadamente a kind: el mensaje subyacente puede ser texto arbitrario, y esta vía nunca emite nada que pueda contener la respuesta de un encuestado.
  • bronze_status figura junto a silver_status porque un candidates vacío puede significar dos cosas distintas —aún no se ha extraído ningún conjunto de datos Bronce, o este cuestionario no contiene ninguna pregunta de texto abierto— y la lista por sí sola no permite distinguirlas.
  • pending_review: true mientras haya alguna de las dos decisiones pendiente: un conjunto de datos Bronce listo con candidatos y sin selección de unidades, o una unidad seleccionada a la espera de la revisión de dimensiones.

Por esta vía nunca sale texto literal de los encuestados. Una categoría se proyecta solo como su id y su etiqueta, y las respuestas de muestra por dimensión no se proyectan en absoluto: ambas existen para la propia pantalla de revisión del investigador en Balansor. Las etiquetas de categoría de una unidad nominal son respuestas de los encuestados, por lo que sus categorías se proyectan como ids con recuentos y sin etiqueta.

La selección de unidades puede escribirse por MCP/REST mediante set_coding_selection (más abajo), porque es un juicio sobre la pregunta, hecho antes de que se haya ejecutado ningún modelo. Clasificar una columna, seleccionar dimensiones, cambiarles el nombre y editar sus categorías no lo son, ni lo serán: son juicios sobre los propios datos del investigador y sobre contenido generado, y deliberadamente no existe ninguna herramienta para ellos en ningún transporte. Un agente que dirija el proceso debe mostrar a su usuario pending_review: true y la lista awaiting_review en lugar de volver a derivar pasándolos por alto. Consulte Codificación de respuestas abiertas para el flujo de trabajo completo.


Establece qué unidades de texto abierto codifica este paquete en categorías. La elección es una decisión de análisis por paquete sobre la receta del conjunto de datos Plata, no una propiedad del cuestionario, y solo puede nombrar columnas que el analista ya haya clasificado como descriptive o nominal (consulte kinds en get_bundle_coding).

Parámetro Tipo Obligatorio Predeterminado Descripción
bundle_id string Sí — UUID del paquete
selected string[] Sí — Conjunto completo de reemplazo de claves de unidad de codificación, en el vocabulario que ofrece candidates de get_bundle_coding

Devuelve: { bundle_id, selected }.

Requiere permisos de gestor y un usuario identificado: se rechazan las llamadas solo con token de servicio, para que una ejecución desatendida no pueda seleccionar en nombre de nadie. Presente al investigador los candidatos y sus kinds y escriba la respuesta que le dé, en lugar de elegir por él. Una unidad sin clasificar o clasificada como identifier se rechaza indicando el motivo y la herramienta no escribe nada; un agente no puede clasificar, así que pida al investigador que lo haga en el selector de codificación de la página Plata.

La lista es un conjunto completo de reemplazo, no un delta, y una lista vacía es una decisión («no codificar nada»), no una omisión. Se rechaza una clave que no sea un candidato en el conjunto de datos Bronce de este paquete, incluido el nombre de columna de una sola iteración de un Roster, que parece una columna real pero no agruparía nada; vuelva a leer la lista de candidatos y seleccione en su lugar la clave de la unidad agrupada. Un cambio de selección es una entrada del conjunto de datos Plata: invalida un Plata listo y todo lo que depende de él, y se aplica en la siguiente derivación (una derivación ya en curso conserva la selección con la que empezó).

Deseleccionar una unidad en la que se apoya un objetivo de calibración no se rechaza aquí: ese conflicto aflora en la derivación, que se rechaza con weighting_factor_deselected, para que la receta pueda corregirse en cualquier orden.


Asigna (o borra) la estrategia de muestreo vigente del paquete, la referencia frente a la que se evalúan selection, fielded y weighted. Requiere permisos de gestor y un usuario identificado (se rechazan las llamadas solo con token de servicio); asignar una estrategia requiere además acceso al proyecto de la propia estrategia. Reasignarla vuelve a calcular esas tres medidas; no toca los objetivos de calibración, que son la instrucción de ponderación.

Parámetro Tipo Obligatorio Predeterminado Descripción
bundle_id string Sí — UUID del paquete
strategy_id string No null Estrategia que se asigna; null borra la asignación

Devuelve: { bundle_id, strategy_id, strategy_name }

Una estrategia de muestreo contiene solo factores de los encuestados. Para evaluar la muestra frente a una cifra externa sobre una respuesta de la encuesta (por ejemplo, la preferencia de partido frente a un resultado electoral), añádala a este paquete como objetivo de calibración solo de referencia con set_calibration_targets.


Edita los objetivos de calibración del paquete: la especificación editable hacia la que ponderan derive_silver/code_open_ends, más los objetivos solo de referencia frente a los que se evalúa la calidad del paquete. Un objetivo con raking es la instrucción de ponderación, no la referencia: la medida ponderada se evalúa frente a la estrategia vigente, de modo que un conjunto de objetivos de calibración que no se ajusta al diseño se refleja como distancia respecto a ese diseño y no como una puntuación perfecta frente a su propio objetivo. Se inicializa una sola vez a partir de los factores de la estrategia vigente la primera vez que un investigador abre la etapa Plata en Balansor; a partir de entonces es independiente de la estrategia vigente. Requiere permisos de gestor y un usuario identificado.

Parámetro Tipo Obligatorio Predeterminado Descripción
bundle_id string Sí — UUID del paquete
weighting object No — Bloque completo de reemplazo {use_strategy_factors, factors}
factors array No — Abreviatura de weighting={factors, use_strategy_factors: false}: proporcionar una lista de factores sin más ya supone renunciar al seguimiento en vivo de la estrategia

Cada factor es {column, target_distribution, name?, factor_type?, bucket_ranges?, role?}: column nombra una columna simple ya presente en el marco codificado (una columna de respuesta del conjunto de datos Bronce o de atributo del encuestado, una dimensión codificada de respuesta abierta o un indicador de opción de selección múltiple), y target_distribution asigna a cada valor su proporción objetivo (con suma 1,0).

role es raked (el valor predeterminado: el conjunto de datos Plata pondera hacia el objetivo) o benchmark (no se pondera sobre él; get_bundle_quality evalúa frente a él la muestra obtenida en campo y la ponderada). Cualquier columna objetivo puede adoptar cualquiera de los dos roles, incluidos los atributos de los encuestados. La llamada reemplaza la lista completa, así que lea los objetivos actuales con get_bundle (allí cada objetivo indica su role) y devuelva cada uno con su rol: un objetivo enviado sin role se guarda como objetivo con raking. Una lista en la que todos los objetivos son de referencia se rechaza con weighting_factor_none_raked, porque el raking no tendría nada sobre lo que ponderar.

Un objetivo también puede nombrar un atributo personalizado del encuestado. Su columna es _custom_<key>, donde <key> es la clave del atributo en el registro del encuestado (_custom_region para custom_attributes.region). Un atributo personalizado solo se extrae a un conjunto de datos cuando lo nombra un factor de una estrategia de muestreo o un objetivo de calibración del paquete, de modo que un objetivo es la forma en que un atributo nuevo entra en el conjunto de datos: no es necesario que ya esté en el conjunto de datos Bronce. Consulte qué atributos contiene el conjunto de datos Bronce en custom_attribute_keys de get_dataset_schema.

Devuelve: { bundle_id, weighting, warnings }. warnings es una lista de observaciones sobre un guardado correcto, vacía cuando no hay nada que decir. Contiene una entrada cuando los objetivos guardados ponderan sobre un atributo personalizado con el que no se extrajo el conjunto de datos Bronce del paquete: vuelva a extraer el Bronce (create_bronze_dataset) antes de derivar el conjunto de datos Plata, o la derivación se rechazará con weighting_attributes_not_extracted. Si ningún encuestado del paquete tiene un atributo con ese nombre, el nombre es incorrecto; corríjalo. Si todavía no hay conjunto de datos Bronce, no hay advertencia, porque la primera extracción escribe todos los atributos nombrados. El texto es la misma frase que ve un investigador al guardar los objetivos en Balansor.

Cada guardado comprueba las claves de cada objetivo con el cuestionario del paquete, para ambos roles, tanto en Balansor como por MCP/REST. Una clave sobre una columna de respuesta debe nombrar una de las opciones de esa pregunta, por código de opción ("1") o por etiqueta de opción ("Yes"); de lo contrario, un código mal escrito en una referencia se evaluaría como un fallo fantasma.

Caso Resultado
Una clave que la pregunta no ofrece Se rechaza (400), nombrando el objetivo, la columna, las claves sin correspondencia y los códigos y etiquetas que acepta: Target 'Recommend' targets keys that are neither an option code nor an option label of 'q_cp07': 'Exit interview' offers no option ['Maybe'] and accepts, by code or label: 1 (Yes), 2 (No).
Una columna cuyas opciones no nombran todos los valores (un control deslizante, texto libre), o un cuestionario que no puede leerse Se guarda, con una entrada en warnings que indica que las claves no se comprobaron
Una columna de atributo del encuestado (_demographic_*, _custom_*), una dimensión codificada de respuesta abierta o un objetivo por tramos Esta regla no la comprueba (siguen aplicándose la comprobación previa de abajo y la derivación)

Estas condiciones se rechazan con un error de conflicto antes de escribir nada; es la misma comprobación previa que ejecuta la propia derivación del conjunto de datos Plata:

  • un objetivo que nombra una categoría de codificación que se rechazó o que ya ha desaparecido de la última ejecución de codificación;
  • un objetivo que nombra una columna de respuesta de selección múltiple sin procesar. Esa columna almacena una combinación de las opciones seleccionadas, de modo que cada combinación observada se convertiría en su propia celda de ponderación. Defina en su lugar los objetivos sobre las columnas indicadoras por opción: un objetivo por opción;
  • dos objetivos sobre la misma columna o con el mismo nombre;
  • una lista en la que todos los objetivos son solo de referencia mientras los objetivos constituyen todo el conjunto de ponderación (use_strategy_factors es false, como ocurre con la abreviatura factors), de modo que el raking no tendría nada sobre lo que ponderar (weighting_factor_none_raked). Un paquete que sigue su estrategia aplica raking sobre los factores de la estrategia y puede contener solo referencias.

Previsualiza la copia de los objetivos de calibración de otro paquete en este. Informa de cuáles de los objetivos de origen encajan en este paquete y cuáles no, y no escribe nada. Para copiar, combine addable con los objetivos actuales de este paquete y guarde el resultado con set_calibration_targets, cuyas comprobaciones vuelven a ejecutarse al guardar. Requiere permisos de gestor, acceso de escritura a este paquete y acceso de lectura al paquete de origen; un origen que usted no puede leer responde exactamente igual que uno inexistente. La página Plata de Balansor ofrece la misma acción como Copiar de otro paquete, que rellena el editor y no guarda nada hasta que usted guarde.

Parámetro Tipo Obligatorio Predeterminado Descripción
bundle_id string Sí — El paquete al que se copiarían los objetivos
source_bundle_id string Sí — El paquete cuyos objetivos se copian

Devuelve: { bundle_id, source_bundle_id, addable, rejected }. addable contiene los objetivos que encajan, cada uno con su role. rejected contiene el resto, cada uno con name, column, role, un detail legible y un reason:

reason Significado
no_bronze Este paquete todavía no tiene conjunto de datos Bronce, así que no hay lista de columnas con la que comprobar; extraiga primero el Bronce
column_missing La columna no está en el conjunto de datos Bronce de este paquete, ni es un atributo del encuestado (_demographic_<field>, _custom_<key>), ni una dimensión codificada de su libro de códigos
unknown_code Una clave no es una opción que el cuestionario de este paquete ofrezca en esa columna (la comprobación de códigos de respuesta)
preflight:<code> El objetivo no superaría aquí una condición de la comprobación previa, p. ej. preflight:weighting_factor_duplicated cuando este paquete ya tiene un objetivo con ese nombre o esa columna. Una lista solo de referencias no es un motivo aquí: eso se juzga sobre la lista que finalmente guarde

La extracción, la codificación + ponderación, el refinamiento y la exportación se invocan todos con un bundle_id en las Herramientas de conjuntos de datos. Un flujo típico:

  1. create_bundle → obtiene el bundle_id
  2. create_bronze_dataset(bundle_id) → extrae el conjunto de datos Bronce
  3. code_open_ends(bundle_id) (o su alias derive_silver) → codifica las respuestas abiertas y luego pondera frente a los objetivos de calibración, y genera así el conjunto de datos Plata
  4. create_gold_dataset(bundle_id, operations=[...]) → refina el conjunto de datos Plata en el conjunto de datos Oro mediante el catálogo de operaciones
  5. export_dataset(dataset_id, format) → exporta cualquier etapa lista
  6. get_bundle_quality(bundle_id) → el resumen de representatividad en cualquier momento

Los pasos 2 a 4 en una sola llamada. Cada paso es la misma herramienta indicada arriba, de modo que se producen los mismos conjuntos de datos y se registran los mismos eventos de auditoría, y cualquier rechazo que daría una etapa por separado se devuelve aquí sin cambios, más stopped_at_step, que indica de qué etapa procede una detención.

Parámetro Tipo Obligatorio Predeterminado Descripción
bundle_id string Sí — El paquete cuya cadena se ejecuta
include_demographics boolean No true Enriquece los registros extraídos del conjunto de datos Bronce con los datos demográficos de los encuestados. false se rechaza con named_attributes_require_enrichment cuando el paquete nombra un atributo personalizado (consulte create_bronze_dataset)
gold_name string No — Nombre del conjunto de datos Oro. De forma predeterminada, "{bundle_name} — Gold"; la receta Oro en sí sigue procediendo de la receta guardada del propio paquete

Devuelve: { task_id, status, step, bundle_id, bronze_dataset_id, silver_dataset_id }. Consulte task_id con get_task_status hasta que la ejecución llegue a completed, partial o failed; la consulta informa de la etapa en la que está la ejecución y, al terminar, del id del conjunto de datos de cada etapa (bronze_dataset_id, silver_dataset_id, gold_dataset_id) y de gold_skipped: las entradas de la receta Oro guardada que la construcción dejó de lado porque el conjunto de datos Plata ya no tiene su columna, con la forma que create_gold_dataset devuelve como skipped. Está vacío cuando no se dejó nada de lado.

Mientras usted espera solo se producen la extracción del conjunto de datos Bronce y la puesta en cola de la derivación del conjunto de datos Plata. La construcción del conjunto de datos Oro no puede empezar hasta que el Plata esté en ready, lo que lleva minutos de codificación y ponderación, por lo que el paso Oro se ejecuta por sí solo cuando termina la derivación y la ejecución puede consultarse en todo momento.

Dos cosas que conviene saber:

  • Una detención conserva lo construido. Un conjunto de datos Bronce es el Bronce del paquete tanto si le siguió un conjunto de datos Oro como si no, así que no se deshace nada. Volver a ejecutar reanuda sobre los mismos registros en lugar de duplicar una etapa.
  • Los derechos de toda la cadena se comprueban antes de construir nada. La cadena abarca tanto el nivel de la pasarela como el del asistente de IA (la derivación con codificación necesita este último), de modo que una suscripción que solo cubre el primero se rechaza de entrada en lugar de recibir un conjunto de datos Bronce del que no puede derivar.