In Hegghammer/daiR: Interface with Google Cloud Document AI API

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
library(knitr)

Note: Some of the functions below, notably get_ids_by_type() and get_versions_by_type() are currently only available in the development version of daiR. Install from Github with devtools::install_github("hegghammer/daiR") to use them.

Google Document AI offers a range of different processors, each optimized for a specific task. For most use cases, the default settings do the job, but there may be situations when you want to use a specific processor type or version. This vignette explains how to do that in daiR.

First, let's clarify some concepts.

• A processor type is a category of processors, such as OCR_PROCESSOR. Google keeps adding new types, but you can find a menu of available processor types at any one time in the official documentation. Many of them are designed for very specific types of documents (like the US tax form "W2") and are thus not relevant to the average user. At the current time of writing there are three main generic processor types, namely, OCR_PROCESSOR, FORM_PARSER_PROCESSOR, and LAYOUT_PARSER_PROCESSOR.

• A processor version is an instance of a processor type, reflecting the fact that different instances have finished training at different points in time. A version can be referenced either by its full name (aka "Version ID"), such as pretrained-ocr-v1.0-2020-09-23, or by its alias, such as stable or rc ("release candidate").

• A processor id is the user-specific identifier of a processor, made up of 16 random characters (for example 3e03a16deqac44a9). When you create a processor for use with Document AI, that processor gets a unique id. Note that one and the same processor can be available in multiple versions.

When you process documents with dai_sync() and dai_async(), you don't normally need to specify a processor, because the functions default to the stable version of the processor you specified in the environment variable DAI_PROCESSOR_ID (see the Configuration vignette). However, you can use the parameters proc_id and proc_v to specify a non-default processor type and version.

To see which processors you have at your disposal at any one time, you can use the function get_processors().

my_processors <- get_processors()

The function returns a dataframe with various metadata for the available processors. If you run this right after setup and you followed the Configuration vignette, you should have only one processor (of type OCR_PROCESSOR), but the dataframe will have several rows; one for each version.

Now let's say you wanted to add a processor of the type FORM_PARSER_PROCESSOR. Then you just need to think of a display name for that processor and pass it to the function create_processor() like so:

## NOT RUN
create_processor("<unique_display_name>", type = "FORM_PARSER_PROCESSOR")

The function will create a processor and output the id in the console. But how do you retrieve the id for a processor that you created some time ago? You can't run create_processor() again, as it would create yet another processor. There are several ways to do this, but the easiest is with the function get_ids_by_type(). It takes the processor type as its main argument, for example like this:

get_ids_by_type("FORM_PARSER_PROCESSOR")

Assuming you have only one processor of this type, the function will return an id which you can then pass to dai_sync()/dai_async() via the proc_id parameter. If you have more than one processor of the type in question, it is better to run get_processors() and pick the right id from the resulting data frame.

A processor is usually available in more than one version, but the range of available versions varies from one processor to another. To find out which versions are available for a given processor, you can use the function get_versions_by_type(), like this:

get_versions_by_type("FORM_PARSER_PROCESSOR")

This function will output both the aliases and the full names of the available versions. Pick the name or alias of the version you want to use and pass it to dai_sync()/dai_async() with the proc_v parameter. You can use either an alias (like rc) or a full name (like pretrained-ocr-v1.0-2020-09-23).

A sample dai_sync() call using a specified processor might look like this:

## NOT RUN
resp <- dai_sync("document.pdf", proc_id = "abcdefgh12345678", proc_v = "rc")

Hegghammer/daiR documentation built on Nov. 15, 2024, 10:34 p.m.