Categorias:: Funções de cadeia de caracteres e binários (funções de AI)

AI_EXTRACT¶

Extrai informações de uma string ou arquivo de entrada.

Sintaxe¶

Extrair informações de uma string de entrada:

AI_EXTRACT( <text>, <responseFormat> )

Copy

AI_EXTRACT( text => <text>,
            responseFormat => <responseFormat> )

Copy

Extrair informações de um arquivo:

AI_EXTRACT( <file>, <responseFormat> )

Copy

AI_EXTRACT( file => <file>,
            responseFormat => <responseFormat> )

Copy

Argumentos¶

text

Uma string de entrada para extração.

file

Um FILE para extração.

Formatos de arquivo compatíveis:

PDF
PNG
PPTX, PPT
EML
DOC, DOCX
JPEG, JPG
HTM, HTML
TEXT, TXT
TIF, TIFF
BMP, GIF, WEBP
MD

Os arquivos devem ter menos de 100 MB de tamanho.

responseFormat

Informações a serem extraídas em um dos seguintes formatos de resposta:

Esquema de objeto simples que mapeia o rótulo e as informações a serem extraídas, por exemplo:

{'name': 'What is the last name of the employee?', 'address': 'What is the address of the employee?'}

Uma matriz de strings com as informações a serem extraídas, por exemplo:

['What is the last name of the employee?', 'What is the address of the employee?']

Uma matriz de matrizes que contém duas strings (o rótulo e as informações a serem extraídas), por exemplo:
```
[['name', 'What is the last name of the employee?'], ['address', 'What is the address of the employee?']]
```
Um esquema JSON que define a estrutura das informações extraídas. Oferece suporte à extração de entidades e tabelas. Por exemplo:
```
{
  'schema': {
    'type': 'object',
    'properties': {
      'income_table': {
        'description': 'Income for FY2026Q2',
        'type': 'object',
        'column_ordering': ['month', 'income'],
        'properties': {
          'month': {
            'description': 'Month',
            'type': 'array'
          },
          'income': {
            'description': 'Income',
            'type': 'array'
          }
        }
      },
      'title': {
        'description': 'What is the title of the document?',
        'type': 'string'
      },
      'employees': {
        'description': 'What are the names of employees?',
        'type': 'array'
      }
    }
  }
}
```
Nota
- Você não pode combinar o JSON Formato de esquema com outros formatos de resposta. Se responseFormat contém o schema Chave, você deve definir todas as perguntas dentro da JSON esquema. Chaves adicionais não são suportadas.
- O modelo aceita apenas certas formas de JSON esquema. O tipo de nível superior deve ser sempre um objeto, que contém subobjetos extraídos independentemente. Os subobjetos podem ser uma tabela (objeto de listas de strings que representam colunas), uma lista de strings ou uma string.
  
  O único tipo escalar compatível atualmente é a string.
- Use o campo description para fornecer contexto ao modelo; por exemplo, para ajudar o modelo a localizar a tabela correta em um documento. Você pode inserir o nome do cabeçalho da coluna ou descrever a coluna de outra maneira.
- Use o campo column_ordering para especificar a ordem de todas as colunas na tabela extraída. O campo column_ordering diferencia maiúsculas de minúsculas e deve corresponder aos nomes das colunas definidos no campo properties. A ordem deve refletir a das colunas no documento.

Retornos¶

Um objeto JSON contendo as informações extraídas.

Exemplo de uma saída que inclui matriz, tabela e extração de valor único:

{
  "error": null,
  "response": {
    "employees": [
      "Smith",
      "Johnson",
      "Doe"
    ],
    "income_table": {
      "income": ["$120 678","$130 123","$150 998"],
      "month": ["February", "March", "April"]
    },
    "title": "Financial report"
  }
}

Requisitos de controle de acesso¶

Os usuários devem usar uma função que tenha a função do banco de dados SNOWFLAKE.CORTEX_USER. Para obter mais informações sobre como conceder esse privilégio, consulte Privilégios de LLM do Cortex.

Notas de uso¶

A AI_EXTRACT é otimizada para documentos originalmente digitais e que foram digitalizados.
Você não pode usar os dois text e file Parâmetros simultaneamente na mesma chamada de função.
Você pode fazer perguntas em linguagem natural ou descrever informações a serem extraídas (como cidade, endereço, código ZIP), por exemplo:
['address': 'City, street, ZIP', 'name': 'First and last name']
Os seguintes idiomas são compatíveis:
- Árabe
- Bengali
- Birmanês
- Cebuano
- Chinês
- Tcheco
- Holandês
- Inglês
- Francês
- Alemão
- Hebraico
- Hindi
- Indonésio
- Italiano
- Japonês
- Quemer
- Coreano
- Lao
- Malaio
- Persa
- Polonês
- Português
- Russo
- Espanhol
- Tagalo
- Tailandês
- Turco
- Urdu
- Vietnamita
Os documentos não devem ter mais de 125 páginas.
Em uma única chamada AI_EXTRACT, você pode fazer no máximo 100 perguntas para extração de entidade e um máximo de 10 perguntas para extração de tabela.

Uma pergunta de extração de tabela é igual a 10 perguntas de extração de entidade. Por exemplo, você pode fazer 4 perguntas de extração de tabela e 60 perguntas de extração de entidade em um único AI_EXTRACT chamar.
O comprimento máximo de saída para extração de entidade é de 512 tokens por pergunta. Para extração de tabela, o modelo retorna respostas com um máximo de 4096 tokens.
Estágios criptografados do lado do cliente não são suportados.
Não há suporte para pontuações de confiança.

Considerações sobre custo¶

A função AI_EXTRACT do Cortex incorre em custo de computação com base no número de páginas por documento, nos tokens de prompts de entrada e nos tokens de saída processados.

Para formatos de arquivo paginados (PDF, DOCX, TIF, TIFF), cada página é contada como 970 tokens.
Para formatos de arquivo de imagem (JPEG, JPG, PNG), cada arquivo de imagem individual é cobrado como uma página e contado como 970 tokens.

O Snowflake recomenda a execução de consultas que chamem a função AI_EXTRACT do Cortex em um warehouse menor (até o tamanho MEDIUM). Warehouses maiores não aumentam o desempenho.

Disponibilidade regional¶

A AI_EXTRACT está disponível para contas nas seguintes regiões:

Plataforma de nuvem	Nome da região
Amazon Web Services (AWS)	US East (N. Virginia) US West (Oregon) Canada (Central) South America (Sao Paulo) EU (Irlanda) EU (Frankfurt) Asia Pacific (Tokyo) Asia Pacific (Sydney)
Microsoft Azure	East US 2 (Virginia) West US 2 (Washington) South Central US (Texas) North Europe (Ireland) West Europe (Netherlands) Southeast Asia (Singapore) Australia East (New South Wales) Central India (Pune) Japan East (Tokyo)

A AI_EXTRACT tem suporte entre regiões. Para obter informações sobre como habilitar o suporte entre regiões do Cortex AI, consulte Inferência entre regiões.

Condições de erro¶

A AI_EXTRACT pode produzir as seguintes mensagens de erro:

Mensagem	Explicação
`Internal error.`	Ocorreu um erro no sistema. Aguarde e tente novamente. Se o problema persistir, entre em contato com o suporte Snowflake.
`Not found.`	O arquivo não foi encontrado.
`Provided file cannot be found.`	O arquivo não foi encontrado.
`Provided file cannot be accessed.`	O usuário atual não tem privilégios suficientes para acessar o arquivo.
`The provided file format {fil_extension} isn't supported.`	O documento não está em um formato compatível.
`The provided file isn't in the expected format or is client-side encrypted or is corrupted.`	O documento não está armazenado em um área de preparação com criptografia do lado do servidor.
`Empty request.`	Nenhum parâmetro foi fornecido.
`Missing or empty response format.`	Nenhum formato de resposta foi fornecido.
`Invalid response format.`	O formato de resposta não é um JSON válido.
`Duplicate feature name found: {feature_name}.`	O formato de resposta contém um ou mais nomes de recursos duplicados.
`Too many questions: {number} complex and {number} simple = {number} total, complex question weight {number}`.	O número de perguntas excede o limite permitido.
`Maximum number of 125 pages exceeded. The document has {actual_pages} pages.`	O documento excede o limite de 125 páginas.
`Page size in pixels exceeds 10000x10000. The page size is {actual_px} pixels.`	A entrada de imagem ou uma página de documento convertida é maior do que as dimensões permitidas.
`Page size in inches exceeds 50x50 (3600x3600 pt). The page size is {actual_in} inches ({actual_pt} pt).`	A página é maior do que as dimensões permitidas.
`Maximum file size of 104857600 bytes exceeded. The file size is {actual_size} bytes.`	O documento tem mais de 100 MB.

Exemplos¶

Extração de uma string de entrada¶

Este exemplo extrai informações do texto de entrada:

SELECT AI_EXTRACT(
  text => 'John Smith lives in San Francisco and works for Snowflake',
  responseFormat => {'name': 'What is the first name of the employee?', 'city': 'What is the address of the employee?'}
);

Copy

Este exemplo extrai e analisa informações do texto de entrada:

SELECT AI_EXTRACT(
  text => 'John Smith lives in San Francisco and works for Snowflake',
  responseFormat => PARSE_JSON('{"name": "What is the first name of the employee?", "address": "What is the address of the employee?"}')
);

Copy

Extração de um arquivo¶

Este exemplo extrai informações do arquivo document.pdf:

SELECT AI_EXTRACT(
  file => TO_FILE('@db.schema.files','document.pdf'),
  responseFormat => [['name', 'What is the first name of the employee?'], ['city', 'Where does the employee live?']]
);

Copy

O seguinte exemplo extrai informações de todos os arquivos em um diretório em uma área de preparação:

Nota

Certifique-se de que a tabela de diretórios esteja habilitada. Para obter mais informações, consulte Manage directory tables.
```
SELECT AI_EXTRACT(
  file => TO_FILE('@db.schema.files', relative_path),
  responseFormat => [
    'What is the document ID?',
    'What is the address of the company?'
  ]
) FROM DIRECTORY (@db.schema.files);
```
Copy

O exemplo a seguir extrai o valor de title do arquivo report.pdf:

SELECT AI_EXTRACT(
  file => TO_FILE('@db.schema.files', 'report.pdf'),
  responseFormat => {
    'schema': {
      'type': 'object',
      'properties': {
        'title': {
          'description': 'What is the title of document?',
          'type': 'string'
        }
      }
    }
  }
);

Copy

O exemplo a seguir extrai a matriz de employees do arquivo report.pdf:

SELECT AI_EXTRACT(
  file => TO_FILE('@db.schema.files', 'report.pdf'),
  responseFormat => {
    'schema': {
      'type': 'object',
      'properties': {
        'employees': {
          'description': 'What are the surnames of employees?',
          'type': 'array'
        }
      }
    }
  }
);

Copy

O exemplo a seguir extrai a tabela income_table do arquivo report.pdf:

SELECT AI_EXTRACT(
  file => TO_FILE('@db.schema.files', 'report.pdf'),
  responseFormat => {
    'schema': {
      'type': 'object',
      'properties': {
        'income_table': {
          'description': 'Income for FY2026Q2',
          'type': 'object',
          'column_ordering': ['month', 'income'],
          'properties': {
            'month': {
              'description': 'Month',
              'type': 'array'
            },
            'income': {
              'description': 'Income',
              'type': 'array'
            }
          }
        }
      }
    }
  }
);

Copy

O exemplo a seguir extrai a tabela (income_table), valor único (title) e matriz (employees) do arquivo report.pdf:

SELECT AI_EXTRACT(
  file => TO_FILE('@db.schema.files', 'report.pdf'),
  responseFormat => {
    'schema': {
      'type': 'object',
      'properties': {
        'income_table': {
          'description': 'Income for FY2026Q2',
          'type': 'object',
          'column_ordering': ['month', 'income'],
          'properties': {
            'month': {
              'description': 'Month',
              'type': 'array'
            },
            'income': {
              'description': 'Income',
              'type': 'array'
            }
          }
        },
        'title': {
          'description': 'What is the title of document?',
          'type': 'string'
        },
        'employees': {
          'description': 'What are the surnames of employees?',
          'type': 'array'
        }
      }
    }
  }
);

Copy

Avisos legais¶

Consulte AI e ML Snowflake para ver os avisos legais.