Confidence and Grounding: Deciding What a Human Must Check

Two different questions

Confidence and grounding are usually mentioned in the same breath, and they answer different questions.

Confidence is a number between zero and one attached to an extracted value. It is the service's own estimate of how reliable that value is. Grounding is a location: the page and the region of the content the value came from, which lets an application draw a box around the evidence or jump a reviewer to the right spot.

One supports automation, the other supports verification. Together they turn extraction output from something you hope is right into something you can act on with a stated policy — and that is the point of the whole feature. The document documentation frames grounded extraction as maintaining traceability so that human-in-the-loop review stays efficient and the process stays transparent.

They are opt-in, and they cost you something

Neither is on by default. You enable them at the analyzer level with the source-and-confidence estimation setting in the config, or per field with the equivalent field-level property, which overrides the analyzer setting. Enabling them selectively is a real design choice: the response grows, and there is little point carrying bounding boxes for a summary nobody will ever verify.

There is one place where the choice is made for you. Fields using the extract method require source and confidence estimation to be switched on. That coupling is logical — extract means the value was taken from a specific place, so the service can always say where — but it means a schema full of extract fields is implicitly a schema with grounding enabled.

The feature is available for all document field types, whether the field generates, classifies or extracts. That is broader than people assume: a generated summary can carry a confidence score and a source region too.

The limitation that catches people is modality. Confidence scores are a document-analyzer feature. Audio, video and image analyzers do not provide them, so review policies for those modalities have to be built from something else — sampling, business rules, or a second check downstream.

Turning numbers into a policy

A confidence score is only useful if it drives a decision, and the decision is a threshold. The guidance is to vary the threshold by how much the field matters rather than picking one number for the whole schema. A contract termination date or an invoice total deserves a high bar; a vendor name a moderate one; a free-text note a low one. The specific numbers quoted in the documentation are explicitly illustrative, and the instruction attached to them is the important part: determine your thresholds experimentally, per use case.

The resulting design is a three-way split rather than a pass-fail gate. Values above the threshold flow straight through to the downstream system. Values below it go to a review queue, where grounding lets the reviewer see the original region without hunting through a hundred-page PDF. Documents where critical fields fail badly may be rejected outright.

This is what straight-through processing means in this context, and it is where the business case lives. The aim is not to eliminate human review but to spend it only where it changes an outcome.

Reading the output honestly

Three misreadings recur.

The first is treating confidence as a probability that the value is correct. It is a reliability estimate produced by the service, and the only way to know what a given threshold buys you on your documents is to measure it against a labelled sample. A field that scores highly and is consistently wrong is possible, which is exactly why the guidance insists on experiment.

The second is expecting an overall document score. Confidence is per field value. A document is not confident or unconfident; twenty fields each have their own number, and your policy has to combine them.

The third is comparing the returned value character-by-character against the page. Supported typed values such as dates and numbers are normalised to a canonical form, that normalisation is not configurable, and the normalised value is what you receive. A date printed one way on the page comes back in canonical form, and a validation rule that expects the printed characters will fail for the wrong reason.

Related switches that look similar

Two neighbouring settings are easy to confuse with this pair. The detailed-results switch controls whether the response includes extra metadata such as spans and bounding information generally, and it inflates response size noticeably. The per-field property overrides the analyzer-level one, so an analyzer can default to lean output while three critical fields carry full grounding.

Knowing which switch produces which part of the response is worth a few marks and, more importantly, prevents the common support ticket where someone insists confidence scores are missing from output that never asked for them.

The design lesson

Build the review path first, then tune thresholds into it. An extraction pipeline with no notion of a low-confidence value has only two states, accepted and unnoticed, and the second is where the expensive mistakes live. With grounding wired into a review screen and per-field thresholds set from measurement, the same pipeline degrades gracefully: it automates most of the volume and asks for help precisely where it is unsure.