OmniDocLos campos faltantes y los campos nulos son dos fallas diferentes.
"Campo no encontrado" y "El campo es un valor nulo" pueden aparecer en blanco en la interfaz, pero no deben confundirse después de ingresar al programa. Luego complete los espacios en blanco con el número cero y el problema será más sutil: el downstream recibe un valor legal, pero cree que proviene del texto original.
Si no se encuentra el campo o el campo tiene un valor nulo, es posible que solo muestre un espacio en blanco en la interfaz, pero el significado es completamente diferente después de ingresar al programa. Si luego el espacio en blanco se llena con el número cero, el downstream obtendrá un valor legal, pero pensará erróneamente que proviene del texto original, lo que hará que el problema sea más difícil de encontrar.
Este artículo está dirigido a desarrolladores y trabajadores de documentos que necesitan entregar los resultados de la extracción a programas para su procesamiento. Explica cómo utilizar el esquema JSON para distinguir tres estados y utilizar varias muestras de entrada para realizar comprobaciones de regresión. Después de leer esto, puede establecer los límites de los valores faltantes, nulos y cero para su propio protocolo de datos.
Los ejemplos de este artículo son datos sintéticos y el código ha sido verificado mediante ejemplos en un entorno aislado, pero esto no representa una garantía de todos los archivos reales o efectos del producto. Antes de procesar documentos importantes, conserve los originales y revíselos de acuerdo con los límites y elementos de aceptación del texto.
Conclusión de una oración
Falta el campo, el valor es null y el valor es 0. Debe haber tres estados diferentes. El contrato debe utilizar la existencia de la clave y el tipo de valor para separarlos. No puede depender de la interfaz ni de conjeturas posteriores.
| tu situación | Prácticas recomendadas | razón |
|---|---|---|
| Es necesario confirmar si la estructura de salida está completa. | Compruebe si la clave existe con required | Las claves que faltan indican que la estructura de salida está incompleta y no equivale a una cantidad de cero. |
| No hay cantidad disponible en el artículo original. | Establezca el valor en null | null significa que no se obtiene ningún valor disponible y no debe completarse con 0 |
| El texto original da explícitamente cero | Usar valor 0 | El cero es un valor inequívoco, a diferencia de los valores nulos y faltantes. |
| Necesidad de explicar el motivo por el que no se extrae | Agregue un campo status o reason adicional y defina los valores permitidos | Evite escribir el motivo en la cadena de cantidad para reducir el desmontaje posterior. |
Primero separe los tres estados
En el contrato de composición de este artículo debe estar presente amount, se permiten valores numéricos o null. Los significados de los tres estados son los siguientes:
- Sin clave
amount: La estructura de salida está incompleta y es una excepción del contrato. amountparanull: la clave existe, pero no hay ninguna cantidad disponible actualmente.amountes 0: hay un valor cero inequívoco.
Se pueden utilizar otros protocolos para negocios reales, pero deben estar claramente escritos y no se puede dejar que cada persona que llama los adivine.
required del esquema JSON es responsable de verificar si la clave existe y type es responsable de verificar el tipo del valor. Dos conceptos erróneos comunes requieren especial atención:
- Simplemente escribir
requiredno desactiva automáticamentenull. - En
propertiessolo se define el campo y no es necesario que aparezca.
Ambos puntos son adecuados para escribir directamente en pruebas de regresión. Para obtener la definición completa de objetos y required, consulte Objetos de esquema JSON y requeridos.
Verificar el contrato con cuatro entradas
from jsonschema import Draft202012Validator
schema = {"type": "object", "required": ["amount"],
"properties": {"amount": {"type": ["number", "null"]}},
"additionalProperties": False}
validator = Draft202012Validator(schema)
valid = lambda value: not list(validator.iter_errors(value))
assert valid({"amount": None})
assert valid({"amount": 0})
assert not valid({})
assert not valid({"amount": "unknown"})
assert not valid({"amount": None, "guessed": True})jsonschema debe instalarse antes de ejecutarse. Este código solo verifica la estructura en la memoria, no llama al modelo de extracción y no puede probar que una cierta cantidad sea consistente con el texto original.
Si la cantidad requiere una representación decimal precisa, se puede utilizar el protocolo de cadena decimal. No piense simplemente en los cálculos binarios de coma flotante como una solución financiera solo porque el ejemplo usa number.
La interfaz también debe indicar claramente el estado.
La visualización en la interfaz también debe distinguir entre estados; de lo contrario, los usuarios malinterpretarán diferentes significados como el mismo resultado.
| datos | El estado que se debe expresar. | no debe mostrarse como |
|---|---|---|
| Sin clave de cantidad | Excepción del contrato de producción | la cantidad es cero |
| la cantidad es nula | No se obtuvo ningún valor disponible | Extracción exitosa |
| la cantidad es 0 | tiene un valor cero claro | Desaparecido |
| la cantidad es una cadena desconocida | No cumple con este contrato | Convertido automáticamente a nulo y pasado silenciosamente |
No inserte motivos faltantes en campos numéricos
Si necesita distinguir entre "texto original no proporcionado", "imagen ilegible", "conflicto de candidatos", etc., puede agregar un campo status o reason adicional y definir valores permitidos para él.
No escriba el motivo en una cadena de cantidad y luego haga que el canal descendente extraiga los números. Desconocido no es lo mismo que fracaso: algunos documentos no tienen este campo y el resultado correcto es dejarlo desconocido.
📊 Comparación central
| estado | ¿Existe la clave? | valor | significado |
|---|---|---|---|
| Desaparecido | No | ninguno | La estructura de salida está incompleta. |
| valor nulo | Sí | null | Actualmente no hay valores disponibles |
| valor cero | Sí | 0 | valor explícito cero |
🎯 ¿Qué método es el adecuado para ti?
Si necesita verificar si la salida de la interfaz está completa
Utilice required para comprobar si la clave existe. Una clave faltante se considera directamente una excepción de contrato.
Si su documento a menudo no tiene un campo determinado
Permita que el valor de este campo sea null y especifique el motivo con status o reason.
Si el monto debe calcularse con precisión
Considere el protocolo de cadena decimal y no confíe directamente en flotantes binarios.
Si desea realizar una traducción o verificación después de la extracción
Verifique la moneda, la procedencia y las etiquetas correspondientes juntas para confirmar que los números clave no se hayan cambiado por error.
❓ Preguntas frecuentes (FAQ)
1. Si solo escribe requerido, ¿eso significa que está prohibido nulo?
No. required solo verifica si la clave existe; la desactivación de null debe definirse por separado en type.
2. ¿Cuál es la diferencia entre un campo nulo y un campo 0?
null significa que actualmente no hay ningún valor disponible, 0 es un valor inequívoco. Ambos deben estar representados en el contrato y la interfaz respectivamente.
3. ¿JSON legal significa que el resultado de la extracción es preciso?
No significa. La inspección estructural sólo puede confirmar que el formato es consistente con el contrato, pero no puede probar que el monto sea consistente con el texto original.
4. ¿Se puede mostrar el campo directamente como 0 cuando falta?
No recomendado. Falta significa que la estructura de salida está incompleta. Completar 0 hará que el flujo descendente lo trate como la cantidad real.
📝 Resumen
Los valores faltantes, nulos y cero tienen sus propios significados y deben expresarse por separado mediante contratos e interfaces. Una vez aprobada la estructura, aún es necesario verificar la moneda, la fuente y la etiqueta correspondiente del monto.
Pruébelo ahora: cargue el documento para comenzar la traducción, conservando el diseño original
