docintel

README

docintel

Client Go para a Azure Document Intelligence, usado para extrair o conteúdo textual de documentos de forma individual ou em lote. Projetado para ser compartilhado entre múltiplos projetos.

Instalação

go get github.com/automatiza-mg/docintel

Requer Go 1.26 ou superior.

Uso

Análise de um documento

A análise é assíncrona: AnalyzeDocument retorna a location da operação, que deve ser consultada com GetAnalyzeResult até atingir um status terminal.

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/automatiza-mg/docintel"
)

func main() {
    client := docintel.NewClient(
        os.Getenv("AZURE_DOCINTEL_ENDPOINT"),
        os.Getenv("AZURE_DOCINTEL_KEY"),
    )

    f, err := os.Open("documento.pdf")
    if err != nil {
        panic(err)
    }
    defer f.Close()

    ctx := context.Background()

    location, err := client.AnalyzeDocument(ctx, docintel.AnalyzeDocumentParams{
        Document:     f,
        ContentType:  "application/pdf",
        Model:        docintel.ModelLayout,
        Locale:       "pt-BR",
        OutputFormat: docintel.ContentFormatMarkdown,
    })
    if err != nil {
        panic(err)
    }

    // Consulte a operação até que ela seja concluída (polling a cargo do chamador).
    for {
        op, err := client.GetAnalyzeResult(ctx, location)
        if err != nil {
            panic(err)
        }

        switch op.Status {
        case docintel.StatusSucceeded:
            fmt.Println(op.AnalyzeResult.Content)
            return
        case docintel.StatusFailed, docintel.StatusCanceled, docintel.StatusSkipped:
            panic(&docintel.AnalyzeError{Status: op.Status, Err: op.Error})
        }
        // StatusRunning / StatusNotStarted: aguarde e tente novamente.
    }
}

Análise em lote

Para processar documentos armazenados no Azure Blob Storage sem enviá-los na requisição, use AnalyzeBatch com uma fonte (AzureBlobSource ou AzureBlobFileListSource) e um container de destino:

location, err := client.AnalyzeBatch(ctx, docintel.AnalyzeBatchParams{
    AzureBlobSource: &docintel.AzureBlobSource{
        ContainerURL: "https://storage.blob.core.windows.net/in?sas",
        Prefix:       "inputDocs/",
    },
    ResultContainerURL: "https://storage.blob.core.windows.net/out?sas",
    ResultPrefix:       "batchResults/",
    OverwriteExisting:  true,
    Model:              docintel.ModelLayout,       // opcional
    OutputFormat:       docintel.ContentFormatText, // opcional
})

Consulte o resultado com GetBatchResult. Os resultados de cada documento são gravados no container de destino, e não retornados na resposta.

Configuração

Parâmetros por chamada

O modelo, o locale e o formato de saída são definidos por chamada, via AnalyzeDocumentParams e AnalyzeBatchParams. Quando omitidos, usam os padrões ModelLayout e ContentFormatMarkdown; o locale vazio deixa a Azure detectar o idioma automaticamente.

Formatos de saída disponíveis (ContentFormat):

• ContentFormatText — texto puro (text).
• ContentFormatMarkdown — Markdown (markdown).

Modelos prebuilt (Model) incluem ModelRead, ModelLayout, ModelInvoice, ModelReceipt, ModelIDDocument, ModelBusinessCard, ModelContract e ModelTaxUSW2. Qualquer ID de modelo custom pode ser usado convertendo a string para docintel.Model.

Client

O client controla a versão da API e o transporte HTTP:

client := docintel.NewClient(endpoint, key,
    docintel.WithAPIVersion("2024-11-30"),
    docintel.WithHTTPClient(customClient), // ex: autenticação via Azure AD
)

Por padrão o client autentica com a API key (header Ocp-Apim-Subscription-Key). Para usar autenticação via Azure AD, injete um *http.Client com um http.RoundTripper próprio usando WithHTTPClient.

Erros

• ErrInvalidAnalyzeRequest: parâmetros de análise de documento inválidos.
• ErrInvalidBatchRequest: parâmetros de análise em lote inválidos.
• ErrOperationNotFound: a operação consultada não existe mais.
• *AnalyzeError: falha no processamento de um documento (carrega o Status).
• *StatusError: resposta HTTP com status inesperado; Retryable() indica se a requisição pode ser repetida (429 e 5xx).

Licença

MIT

Documentation

Overview

Package docintel fornece um client para a API da Azure Document Intelligence, permitindo extrair o conteúdo textual de documentos de forma individual (Client.AnalyzeDocument) ou em lote (Client.AnalyzeBatch).

As operações são assíncronas: os métodos de análise retornam a location da operação, que deve ser consultada com Client.GetAnalyzeResult ou Client.GetBatchResult até que a operação atinja um status terminal.

O modelo, o locale e o formato de saída são definidos por chamada, via AnalyzeDocumentParams e AnalyzeBatchParams.

Index

• Variables
• type AnalyzeBatchParams
• type AnalyzeDocumentParams
• type AnalyzeError
  • func (e *AnalyzeError) Error() string
• type AnalyzeOperation
• type AnalyzeResult
• type AnalyzedDocument
• type AzureBlobFileListSource
• type AzureBlobSource
• type AzureError
• type BatchAnalyzeOperation
• type BatchResult
• type BatchResultDetail
• type BoundingRegion
• type Client
  • func NewClient(endpoint, key string, opts ...Option) *Client
  • func (c *Client) AnalyzeBatch(ctx context.Context, params AnalyzeBatchParams) (string, error)
  • func (c *Client) AnalyzeDocument(ctx context.Context, params AnalyzeDocumentParams) (string, error)
  • func (c *Client) GetAnalyzeResult(ctx context.Context, location string) (*AnalyzeOperation, error)
  • func (c *Client) GetBatchResult(ctx context.Context, location string) (*BatchAnalyzeOperation, error)
• type ContentFormat
• type DocumentCaption
• type DocumentField
• type DocumentFigure
• type DocumentKeyValueElement
• type DocumentKeyValuePair
• type DocumentLanguage
• type DocumentLine
• type DocumentPage
• type DocumentParagraph
• type DocumentSection
• type DocumentStyle
• type DocumentTable
• type DocumentTableCell
• type DocumentWord
• type Model
• type Option
  • func WithAPIVersion(version string) Option
  • func WithHTTPClient(client *http.Client) Option
• type Span
• type Status
• type StatusError
  • func (e *StatusError) Error() string
  • func (e *StatusError) Retryable() bool
• type Warning

Variables

var ErrInvalidAnalyzeRequest = errors.New("docintel: invalid analyze request")

ErrInvalidAnalyzeRequest é retornado quando os parâmetros de uma análise de documento são inválidos.

var ErrInvalidBatchRequest = errors.New("docintel: invalid batch request")

ErrInvalidBatchRequest é retornado quando os parâmetros de uma análise em lote são inválidos.

var ErrOperationNotFound = errors.New("docintel: operation not found")

ErrOperationNotFound é retornado quando a operação consultada não existe mais.

Types

type AnalyzeBatchParams

type AnalyzeBatchParams struct {
	AzureBlobSource         *AzureBlobSource         `json:"azureBlobSource,omitempty"`
	AzureBlobFileListSource *AzureBlobFileListSource `json:"azureBlobFileListSource,omitempty"`

	ResultContainerURL string `json:"resultContainerUrl"`
	ResultPrefix       string `json:"resultPrefix,omitempty"`
	OverwriteExisting  bool   `json:"overwriteExisting,omitempty"`

	Model        Model         `json:"-"`
	Locale       string        `json:"-"`
	OutputFormat ContentFormat `json:"-"`
}

AnalyzeBatchParams agrupa os parâmetros para iniciar uma análise em lote.

Exatamente uma fonte deve ser informada: AzureBlobSource (todos os documentos de um container ou prefixo) ou AzureBlobFileListSource (documentos específicos listados em um arquivo JSONL). Caso ambas ou nenhuma sejam informadas, Client.AnalyzeBatch retorna ErrInvalidBatchRequest.

Model e OutputFormat usam, respectivamente, ModelLayout e ContentFormatMarkdown quando vazios. Locale é opcional: quando vazio, a Azure detecta o idioma automaticamente. Esses três campos são enviados como parâmetros de query e não fazem parte do corpo JSON da requisição.

type AnalyzeDocumentParams

type AnalyzeDocumentParams struct {
	Document     io.Reader
	ContentType  string
	Model        Model
	Locale       string
	OutputFormat ContentFormat
}

AnalyzeDocumentParams agrupa os parâmetros para analisar um documento individual.

Document e ContentType são obrigatórios. Model e OutputFormat usam, respectivamente, ModelLayout e ContentFormatMarkdown quando vazios. Locale é opcional: quando vazio, a Azure detecta o idioma automaticamente.

type AnalyzeError

type AnalyzeError struct {
	Status Status
	Err    *AzureError
}

AnalyzeError é retornado quando há falha ao processar algum documento.

func (*AnalyzeError) Error

func (e *AnalyzeError) Error() string

type AnalyzeOperation

type AnalyzeOperation struct {
	Status              Status        `json:"status"`
	CreatedDateTime     time.Time     `json:"createdDateTime"`
	LastUpdatedDateTime time.Time     `json:"lastUpdatedDateTime"`
	AnalyzeResult       AnalyzeResult `json:"analyzeResult"`
	Error               *AzureError   `json:"error,omitempty"`
}

type AnalyzeResult

type AnalyzeResult struct {
	APIVersion      string                 `json:"apiVersion"`
	ModelID         string                 `json:"modelId"`
	Content         string                 `json:"content"`
	StringIndexType string                 `json:"stringIndexType"`
	ContentFormat   string                 `json:"contentFormat"`
	Pages           []DocumentPage         `json:"pages,omitempty"`
	Paragraphs      []DocumentParagraph    `json:"paragraphs,omitempty"`
	Tables          []DocumentTable        `json:"tables,omitempty"`
	Figures         []DocumentFigure       `json:"figures,omitempty"`
	Sections        []DocumentSection      `json:"sections,omitempty"`
	KeyValuePairs   []DocumentKeyValuePair `json:"keyValuePairs,omitempty"`
	Languages       []DocumentLanguage     `json:"languages,omitempty"`
	Styles          []DocumentStyle        `json:"styles,omitempty"`
	Documents       []AnalyzedDocument     `json:"documents,omitempty"`
	Warnings        []Warning              `json:"warnings,omitempty"`
}

AnalyzeResult representa o resultado da análise de um documento.

type AnalyzedDocument

type AnalyzedDocument struct {
	DocType         string                   `json:"docType"`
	BoundingRegions []BoundingRegion         `json:"boundingRegions,omitempty"`
	Spans           []Span                   `json:"spans,omitempty"`
	Fields          map[string]DocumentField `json:"fields,omitempty"`
	Confidence      float64                  `json:"confidence"`
}

AnalyzedDocument representa um documento extraído pelo modelo.

type AzureBlobFileListSource

type AzureBlobFileListSource struct {
	ContainerURL string `json:"containerUrl"`
	FileList     string `json:"fileList"`
}

AzureBlobFileListSource especifica documentos a serem processados em lote por meio de um arquivo JSONL armazenado na raiz do container.

type AzureBlobSource

type AzureBlobSource struct {
	ContainerURL string `json:"containerUrl"`
	Prefix       string `json:"prefix,omitempty"`
}

AzureBlobSource especifica um container (opcionalmente filtrado por prefixo) cujos documentos serão processados em lote.

type AzureError

type AzureError struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

type BatchAnalyzeOperation

type BatchAnalyzeOperation struct {
	ResultID            string      `json:"resultId"`
	Status              Status      `json:"status"`
	PercentCompleted    int         `json:"percentCompleted"`
	CreatedDateTime     time.Time   `json:"createdDateTime"`
	LastUpdatedDateTime time.Time   `json:"lastUpdatedDateTime"`
	Result              BatchResult `json:"result"`
	Error               *AzureError `json:"error,omitempty"`
}

BatchAnalyzeOperation representa o status de uma operação de análise em lote da Azure Document Intelligence.

O resultado não contém o conteúdo extraído dos documentos: cada documento processado com sucesso aponta para um arquivo de resultado via BatchResultDetail.ResultURL.

type BatchResult

type BatchResult struct {
	SucceededCount int                 `json:"succeededCount"`
	FailedCount    int                 `json:"failedCount"`
	SkippedCount   int                 `json:"skippedCount"`
	Details        []BatchResultDetail `json:"details,omitempty"`
}

BatchResult agrega o resultado de uma operação de análise em lote.

type BatchResultDetail

type BatchResultDetail struct {
	SourceURL string      `json:"sourceUrl"`
	ResultURL string      `json:"resultUrl,omitempty"`
	Status    Status      `json:"status"`
	Error     *AzureError `json:"error,omitempty"`
}

BatchResultDetail representa o resultado do processamento de um único documento em um lote.

type BoundingRegion

type BoundingRegion struct {
	PageNumber int       `json:"pageNumber"`
	Polygon    []float64 `json:"polygon,omitempty"`
}

BoundingRegion associa um conteúdo a uma região (polígono) em uma página.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client é o client da API da Azure Document Intelligence.

func NewClient

func NewClient(endpoint, key string, opts ...Option) *Client

NewClient cria um Client para o endpoint informado, autenticado com a API key (header Ocp-Apim-Subscription-Key).

Sem Option, o client usa a versão de API "2024-11-30". Use WithAPIVersion para alterá-la ou WithHTTPClient para injetar um http.Client próprio (ex: para autenticação via Azure AD).

func (*Client) AnalyzeBatch

func (c *Client) AnalyzeBatch(ctx context.Context, params AnalyzeBatchParams) (string, error)

AnalyzeBatch inicia a análise em lote de documentos armazenados no Azure Blob Storage, extraindo texto no formato configurado usando a API da Azure Document Intelligence.

Os documentos não são enviados diretamente: a fonte e o destino dos resultados são containers do Blob Storage informados em params. Os resultados de cada documento são gravados como arquivos no container de destino e não fazem parte da resposta.

Retorna o local da operação para ser consultado usando Client.GetBatchResult. Retorna ErrInvalidBatchRequest caso os parâmetros sejam inválidos.

func (*Client) AnalyzeDocument

func (c *Client) AnalyzeDocument(ctx context.Context, params AnalyzeDocumentParams) (string, error)

AnalyzeDocument inicia a análise de um documento (extraindo o conteúdo no formato configurado) a partir de um io.Reader usando a API da Azure Document Intelligence.

Retorna o local da operação para ser consultado usando Client.GetAnalyzeResult. Retorna ErrInvalidAnalyzeRequest caso os parâmetros sejam inválidos.

func (*Client) GetAnalyzeResult

func (c *Client) GetAnalyzeResult(ctx context.Context, location string) (*AnalyzeOperation, error)

GetAnalyzeResult retorna o status e, quando concluído, o resultado da análise do documento.

Retorna ErrOperationNotFound caso a operação não exista mais.

func (*Client) GetBatchResult

func (c *Client) GetBatchResult(ctx context.Context, location string) (*BatchAnalyzeOperation, error)

GetBatchResult retorna o status e, quando concluído, o resultado da análise em lote.

Retorna ErrOperationNotFound caso a operação não exista mais.

type ContentFormat

type ContentFormat string

ContentFormat é o formato do conteúdo extraído, informado no parâmetro outputContentFormat das operações de análise.

const (
	// ContentFormatText extrai o conteúdo como texto puro.
	ContentFormatText ContentFormat = "text"
	// ContentFormatMarkdown extrai o conteúdo em Markdown.
	ContentFormatMarkdown ContentFormat = "markdown"
)

type DocumentCaption

type DocumentCaption struct {
	Content         string           `json:"content"`
	BoundingRegions []BoundingRegion `json:"boundingRegions,omitempty"`
	Spans           []Span           `json:"spans,omitempty"`
}

DocumentCaption representa a legenda de uma figura ou tabela.

type DocumentField

type DocumentField struct {
	Type            string           `json:"type"`
	Content         string           `json:"content,omitempty"`
	BoundingRegions []BoundingRegion `json:"boundingRegions,omitempty"`
	Spans           []Span           `json:"spans,omitempty"`
	Confidence      float64          `json:"confidence,omitempty"`
}

DocumentField representa um campo extraído de um documento.

type DocumentFigure

type DocumentFigure struct {
	ID              string           `json:"id,omitempty"`
	Caption         *DocumentCaption `json:"caption,omitempty"`
	BoundingRegions []BoundingRegion `json:"boundingRegions,omitempty"`
	Spans           []Span           `json:"spans,omitempty"`
}

DocumentFigure representa uma figura extraída do documento.

type DocumentKeyValueElement

type DocumentKeyValueElement struct {
	Content         string           `json:"content"`
	BoundingRegions []BoundingRegion `json:"boundingRegions,omitempty"`
	Spans           []Span           `json:"spans,omitempty"`
}

DocumentKeyValueElement representa a chave ou o valor de um par chave-valor.

type DocumentKeyValuePair

type DocumentKeyValuePair struct {
	Key        DocumentKeyValueElement  `json:"key"`
	Value      *DocumentKeyValueElement `json:"value,omitempty"`
	Confidence float64                  `json:"confidence"`
}

DocumentKeyValuePair representa um par chave-valor extraído do documento.

type DocumentLanguage

type DocumentLanguage struct {
	Locale     string  `json:"locale"`
	Spans      []Span  `json:"spans,omitempty"`
	Confidence float64 `json:"confidence"`
}

DocumentLanguage representa um idioma detectado no documento.

type DocumentLine

type DocumentLine struct {
	Content string    `json:"content"`
	Polygon []float64 `json:"polygon,omitempty"`
	Spans   []Span    `json:"spans,omitempty"`
}

DocumentLine representa uma linha de texto detectada em uma página.

type DocumentPage

type DocumentPage struct {
	PageNumber int            `json:"pageNumber"`
	Angle      float64        `json:"angle,omitempty"`
	Width      float64        `json:"width,omitempty"`
	Height     float64        `json:"height,omitempty"`
	Unit       string         `json:"unit,omitempty"`
	Spans      []Span         `json:"spans,omitempty"`
	Words      []DocumentWord `json:"words,omitempty"`
	Lines      []DocumentLine `json:"lines,omitempty"`
}

DocumentPage representa uma página analisada do documento.

type DocumentParagraph

type DocumentParagraph struct {
	Role            string           `json:"role,omitempty"`
	Content         string           `json:"content"`
	BoundingRegions []BoundingRegion `json:"boundingRegions,omitempty"`
	Spans           []Span           `json:"spans,omitempty"`
}

DocumentParagraph representa um parágrafo extraído do documento.

type DocumentSection

type DocumentSection struct {
	Spans    []Span   `json:"spans,omitempty"`
	Elements []string `json:"elements,omitempty"`
}

DocumentSection representa uma seção identificada no documento.

type DocumentStyle

type DocumentStyle struct {
	IsHandwritten   bool    `json:"isHandwritten,omitempty"`
	Color           string  `json:"color,omitempty"`
	BackgroundColor string  `json:"backgroundColor,omitempty"`
	FontStyle       string  `json:"fontStyle,omitempty"`
	FontWeight      string  `json:"fontWeight,omitempty"`
	Spans           []Span  `json:"spans,omitempty"`
	Confidence      float64 `json:"confidence"`
}

DocumentStyle representa um estilo de fonte detectado no documento.

type DocumentTable

type DocumentTable struct {
	RowCount        int                 `json:"rowCount"`
	ColumnCount     int                 `json:"columnCount"`
	Cells           []DocumentTableCell `json:"cells,omitempty"`
	BoundingRegions []BoundingRegion    `json:"boundingRegions,omitempty"`
	Spans           []Span              `json:"spans,omitempty"`
}

DocumentTable representa uma tabela extraída do documento.

type DocumentTableCell

type DocumentTableCell struct {
	Kind            string           `json:"kind,omitempty"`
	RowIndex        int              `json:"rowIndex"`
	ColumnIndex     int              `json:"columnIndex"`
	RowSpan         int              `json:"rowSpan,omitempty"`
	ColumnSpan      int              `json:"columnSpan,omitempty"`
	Content         string           `json:"content"`
	BoundingRegions []BoundingRegion `json:"boundingRegions,omitempty"`
	Spans           []Span           `json:"spans,omitempty"`
}

DocumentTableCell representa uma célula de uma tabela.

type DocumentWord

type DocumentWord struct {
	Content    string    `json:"content"`
	Polygon    []float64 `json:"polygon,omitempty"`
	Span       Span      `json:"span"`
	Confidence float64   `json:"confidence"`
}

DocumentWord representa uma palavra detectada em uma página.

type Model

type Model string

Model identifica o modelo usado na análise (modelId).

Além das constantes de modelos prebuilt declaradas abaixo, qualquer ID de modelo custom pode ser usado convertendo a string para Model.

const (
	// ModelRead detecta linhas, palavras, localizações e idiomas.
	ModelRead Model = "prebuilt-read"
	// ModelLayout extrai texto, tabelas, marcas de seleção e estrutura.
	ModelLayout Model = "prebuilt-layout"
	// ModelInvoice extrai campos de notas fiscais e faturas.
	ModelInvoice Model = "prebuilt-invoice"
	// ModelReceipt extrai campos de recibos.
	ModelReceipt Model = "prebuilt-receipt"
	// ModelIDDocument extrai campos de documentos de identidade.
	ModelIDDocument Model = "prebuilt-idDocument"
	// ModelBusinessCard extrai campos de cartões de visita.
	ModelBusinessCard Model = "prebuilt-businessCard"
	// ModelContract extrai campos de contratos.
	ModelContract Model = "prebuilt-contract"
	// ModelTaxUSW2 extrai campos de formulários fiscais W-2 dos EUA.
	ModelTaxUSW2 Model = "prebuilt-tax.us.w2"
)

type Option

type Option func(*Client)

Option configura um Client criado por NewClient.

func WithAPIVersion

func WithAPIVersion(version string) Option

WithAPIVersion define a versão da API usada nas requisições (padrão "2024-11-30").

func WithHTTPClient

func WithHTTPClient(client *http.Client) Option

WithHTTPClient substitui o http.Client usado nas requisições.

Útil para configurar timeouts, proxies ou uma autenticação diferente da API key padrão (ex: um http.RoundTripper que injeta um token do Azure AD). O client informado é usado como está, sem adicionar o header de API key.

type Span

type Span struct {
	Offset int `json:"offset"`
	Length int `json:"length"`
}

Span representa um intervalo (offset e comprimento) no conteúdo concatenado do resultado.

type Status

type Status string

Status representa o estado de uma operação de análise da Azure Document Intelligence.

const (
	StatusNotStarted Status = "notStarted"
	StatusRunning    Status = "running"
	StatusSucceeded  Status = "succeeded"
	StatusFailed     Status = "failed"
	StatusCanceled   Status = "canceled"
	StatusSkipped    Status = "skipped"
	// StatusCompleted é o status terminal de sucesso de uma operação em lote.
	// Os documentos individuais usam os demais status (ex: [StatusSucceeded]).
	StatusCompleted Status = "completed"
)

type StatusError

type StatusError struct {
	StatusCode int
	Body       string
}

StatusError representa uma resposta HTTP com status inesperado.

func (*StatusError) Error

func (e *StatusError) Error() string

func (*StatusError) Retryable

func (e *StatusError) Retryable() bool

Retryable indica se o erro pode ser repetido. Status 429 (Too Many Requests) e erros 5xx são considerados temporários.

type Warning

type Warning struct {
	Code    string `json:"code"`
	Message string `json:"message"`
	Target  string `json:"target,omitempty"`
}

Warning representa um aviso encontrado durante a análise.