Troubleshooting AI_EXTRACT: Errors, Privileges, Cost and Fine-Tuning

1.Extracting query errors and opening the document with GET_PRESIGNED_URL

When you run AI_EXTRACT over a whole directory of files, one bad document does not need to stop you from reading the others. Each result is a JSON object, and the error key sits beside response. On a successful call error is null. When you troubleshoot a batch, you separate the rows whose error is not null from the rows that came back with answers, and then you read the message.

{
  "error": null,
  "response": {
    "title": "Financial report"
  }
}

Most of the documented messages point to a single fix. Some are about the file: it is missing, you are not allowed to read it, or it is in the wrong format. Some are about the request: it is empty, it is not valid JSON, it reuses a key, or it asks too many questions. The rest are about size: page count, page dimensions or file size. "Not found" and "cannot be accessed" look alike but mean different things. The first is a path problem. The second means the current user lacks privileges on the file.

After you have isolated a failing row, or a successful row whose answer looks wrong, the next step is to look at the document yourself. GET_PRESIGNED_URL is the file function that makes this possible. You give it a stage name and a relative path, and it returns a URL that you can open in a web browser, click in a Snowsight results table, or send to the REST API for file support. The documentation describes the two functions separately. Pairing them in a review workflow is a practical pattern, not a documented feature.

GET_PRESIGNED_URL( @<stage_name> , '<relative_file_path>' , [ <expiration_time> ] )

SELECT GET_PRESIGNED_URL(@images_stage, 'us/yosemite/half_dome.jpg', 3600);

The expiration_time is in seconds and defaults to 3600. The ceiling depends on the stage. It is 3600 when the stage connects to S3 through an AWS IAM role (AWS_ROLE) and for Microsoft Fabric OneLake stages, and 604800 (7 days) otherwise. On OneLake, asking for more than the limit returns an error. On an Azure external stage, the function only works when the container is accessed through a storage integration. Querying it fails if the container uses a SAS token you generated. If a stage name contains spaces or special characters, wrap it in single quotes, for example '@"my stage"'.

One behaviour catches people out during troubleshooting. The function does not check that the file exists. It will return a well-formed URL for a misspelled path, and you only find out when the browser shows a NoSuchKey error in XML.

Sources12

2.Requirements and privileges

Some errors, such as "cannot be accessed", come from missing privileges rather than from the document. The privileges build up in layers. To call AI_EXTRACT at all, your role needs the SNOWFLAKE.CORTEX_USER database role. Reading the file comes next, and GET_PRESIGNED_URL is a good example of how stage privileges work: on an internal stage the role needs READ, and on an external stage it needs USAGE.

Encryption is a separate requirement, and the three features you use while troubleshooting do not agree on it:

- AI_EXTRACT reads documents on stages with client-side or server-side encryption, including in accounts that restrict public network access to stages with PrivateLink or network policies. - GET_PRESIGNED_URL requires server-side encryption on the stage. If files downloaded from an internal stage are corrupted, check that the stage was created with ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE'). - Fine-tuning arctic-extract does not support client-side encrypted stages, and it does not currently work with custom network policies.

So a stage that AI_EXTRACT reads without trouble can still fail when you try to fine-tune from it or create presigned URLs for it.

Fine-tuning needs the most privileges. The ACCOUNTADMIN role must grant SNOWFLAKE.CORTEX_USER to the calling user. The job then needs access to the database and schema that hold the Dataset, to the stage that holds the documents, and to the schema where the tuned model will be created. After training, anyone who runs inference with the tuned model needs OWNERSHIP, USAGE and READ on the model object.

Sources1234

3.Cost and best-practice considerations

AI_EXTRACT bills compute for three things: pages, input prompt tokens and output tokens. For paged formats (PDF, DOCX, TIF, TIFF), each page counts as 970 tokens. Image files (JPEG, JPG, PNG) are billed as one page each, also at 970 tokens. Because of this, sending an extra 40-page appendix through the function costs money even if none of your questions are about it. Warehouse size does not help: Snowflake recommends MEDIUM or smaller because larger warehouses don’t increase performance. Requesting scores => TRUE costs nothing extra.

The config argument's scale_factor (1.0 to 4.0) enlarges each page before the model reads it. It is the setting to try when answers have character-level OCR typos, when text is small or layouts are dense, or when pages are larger than A4. It has two costs. Input tokens grow in proportion to the factor, and the maximum number of pages per document shrinks by the same factor.

Each call also has a question budget: at most 100 entity questions and at most 10 table questions. A table question weighs as much as 10 entity questions, so 4 tables plus 60 entities fill the budget exactly. Going over it triggers the "Too many questions" error from the first section. Entity answers are capped at 512 output tokens per question. Table answers are capped at 4096 tokens, and the model simply stops extracting when it reaches that limit. If a table spans several pages, split the document into one-page documents and join the results afterwards. If a single page is still too dense, split the table by columns, for example two definitions of five columns each instead of one with ten.

Most table-extraction accuracy problems can be fixed in how you write the response format:

- Keep each workload to documents of the same type. - Copy column names exactly as they appear in the document (Report Date, not REPORT_DATE). Avoid meaningless names such as col1. - Define columns in document order. Put columns whose value repeats across rows, such as Invoice Number and Invoice Date, first. - Add a Section column (and a Subsection column if needed) when the table is divided into named sections. - Flatten hierarchical headers by prefixing each column with its parent names. - Fill in the optional description field only when similar tables confuse the model, and give the table title or number.

For entity questions, use plain English, ask for one value per question, and be specific. "What is the date?" is ambiguous on a form that has both an issue date and a signature date.

Because scores are free, you can use them to flag low-scoring extractions for human review instead of re-running whole batches. Each list or table gets a single aggregate score. Individual items and cells are not scored.

Sources13

4.Fine-tuning arctic-extract models

If better prompts, table definitions and scale_factor still leave accuracy too low for a document type, the last option is to fine-tune. You train arctic-extract with the Cortex FINETUNE function on a Snowflake Dataset, then call the resulting model from AI_EXTRACT. FINETUNE has four modes: CREATE, DESCRIBE, SHOW and CANCEL. CREATE takes a model name, the base model 'arctic-extract', a training Dataset, and optionally a validation Dataset and an options JSON.

SELECT SNOWFLAKE.CORTEX.FINETUNE(
  'CREATE',
  '@database.schema.model_name',
  'arctic-extract',
  'snow://dataset/training_ds/versions/2',
  'snow://dataset/validation_ds/versions/4',
  '{"max_epochs": 3}'
);

max_epochs takes an integer from 2 to 10. If you leave out options, the system chooses the number of epochs. The Dataset must contain three columns. File is a stage path such as @db.schema.stage/file.pdf. Prompt holds the questions, in any format that AI_EXTRACT's responseFormat accepts. Response holds the answers, matched to the questions by key. Column names are case-insensitive and can appear in any order. Extra columns are ignored, but missing any of the three makes the Dataset invalid. Documents do not all need the same questions, and the model's schema is the unique set of questions across the Dataset. Set the response to None when a document has no answer. Also add rows even where the base model already answers correctly, because that confirms the answer is right. The limits below are hard requirements, and the per-question limits differ from the per-call AI_EXTRACT budget only in that here they count unique questions across the whole Dataset.

FINETUNE('DESCRIBE') reports on a job: its status, its progress (1.0 when finished), the number of trained tokens, and a training_result with training_loss and validation_loss. You can only see a validation loss if you supplied a validation Dataset. When the status is SUCCESS, pass the model to AI_EXTRACT with the model argument. You can override the questions it was trained on with responseFormat, combine it with config => {'scale_factor': 2.0}, and request scores, which are supported for fine-tuned models. A tuned model can also be copied between databases, schemas and accounts.

SELECT AI_EXTRACT(
   ?  => 'db.schema.my_tuned_model',
  file => TO_FILE('@db.schema.files','document.pdf')
);

Sources41

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.If GET_PRESIGNED_URL returns a URL, the file exists on the stage.Why is that wrong?

   The function returns a URL for any path you give it. You only find out the file is missing when you open the URL and get a NoSuchKey error.

   Covered in Extracting query errors and opening the document with GET_PRESIGNED_URL

2. 2.If AI_EXTRACT can read documents on a stage, fine-tuning can use that stage too.Why is that wrong?

   AI_EXTRACT accepts client-side encrypted stages and restricted networks, but fine-tuning does not. It rejects client-side encrypted stages and does not work with custom network policies.

   Covered in Requirements and privileges

3. 3.A larger warehouse makes AI_EXTRACT run faster.Why is that wrong?

   Snowflake recommends a warehouse no larger than MEDIUM, because larger warehouses do not improve AI_EXTRACT performance.

   Covered in Cost and best-practice considerations

4. 4.A table question uses one slot of the 100-question budget, just like an entity question.Why is that wrong?

   A table question counts as 10 entity questions, so a few tables quickly use up the per-call budget and trigger the Too many questions error.

   Covered in Cost and best-practice considerations