AI_EXTRACT¶

Sintaxe¶

Extrair informações de uma string de entrada:

AI_EXTRACT( <text>, <responseFormat> )

AI_EXTRACT( text => <text>,
            responseFormat => <responseFormat>,
            [ scores => TRUE | FALSE ] )

Extrair informações de um arquivo:

AI_EXTRACT( <file>, <responseFormat> )

AI_EXTRACT( file => <file>,
            responseFormat => <responseFormat>,
            [ config => <config_object> ],
            [ scores => TRUE | FALSE ] )

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. O formato depende do tipo de extração.

Formatos de extração de entidades

Extraia valores individuais fornecendo um dos seguintes formatos:

• Esquema de objeto simples que mapeia o rótulo e a informação a ser extraída:

  Expand

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

  Show lessSee more

  Scroll to top

• Uma matriz de cadeias de caracteres que contém a informação a ser extraída:

  Expand

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

  Show lessSee more

  Scroll to top

• Uma matriz de matrizes que contém duas cadeias de caracteres (rótulo e a informação a ser extraída):

  Expand

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

  Show lessSee more

  Scroll to top

• Um esquema JSON com 'type': 'string' no subobjeto:

  Expand

  {
    'schema': {
      'type': 'object',
      'properties': {
        'title': {
          'description': 'What is the title of the document?',
          'type': 'string'
        }
      }
    }
  }
  

  Show lessSee more

  Scroll to top

Formato de extração de lista

Extraia matrizes de valores usando um esquema JSON com 'type': 'array' no subobjeto:

Expand

{
  'schema': {
    'type': 'object',
    'properties': {
      'employees': {
        'description': 'What are the names of employees?',
        'type': 'array'
      }
    }
  }
}

Show lessSee more

Scroll to top

Formato de extração de tabela

Extraia dados tabulares usando um esquema JSON com 'type': 'object' e column_ordering. Cada coluna é definida como uma propriedade aninhada com 'type': 'array' e um description que corresponde ao nome da coluna no arquivo:

Expand

{
  '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'
          }
        }
      }
    }
  }
}

Show lessSee more

Scroll to top

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 a description campo 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 forma.

• 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 ordem das colunas no documento.

scores => boolean

Opcional. Compatível apenas com a sintaxe de argumento nomeado mostrada acima. Um BOOLEAN que controla se a função retorna pontuações para valores extraídos. O padrão é FALSE. Quando TRUE, o resultado do JSON inclui um objeto scoring além de response. Para consultar o formato de saída, os exemplos de SQL e as limitações, veja Pontuações de extração (versão preliminar).

config => config_object

Um valor OBJECT que especifica as configurações. É possível usar uma constante OBJECT para especificar esse objeto.

Você pode especificar os seguintes pares chave-valor neste objeto:

Chave

Descrição

scale_factor

Um valor numérico de 1,0 a 4,0. Redimensiona as páginas de um arquivo de entrada antes de serem processadas pelo modelo subjacente, o que pode melhorar a qualidade do OCR e os resultados da extração. Use scale_factor se você receber respostas inesperadas ou pouco claras nos seguintes cenários: Documentos com tamanhos de página maiores que A4 Documentos com texto pequeno, elementos visuais detalhados ou layouts densos Texto extraído com erros de digitação ou de OCR no nível de caractere Se omitido, o AI_EXTRACT usará o valor padrão ('scale_factor': 1.0).

See moreShow less

Expand

Retornos¶

Um objeto JSON contendo as informações extraídas. A estrutura da resposta depende do tipo de extração.

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

{
  "error": null,
  "response": {
    "employees": [
      "Smith",
      "Johnson",
      "Doe"
    ]
  }
}

{
  "error": null,
  "response": {
    "income_table": {
      "income": ["$120 678","$130 123","$150 998"],
      "month": ["February", "March", "April"]
    }
  }
}

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

Pontuações de extração (versão preliminar)¶

Quando você usa AI_EXTRACT, pode solicitar pontuações que indicam a certeza do modelo sobre cada valor extraído. Você pode usar as pontuações para definir limites para lógica de negócios, como sinalizar extrações de pontuação baixa para revisão humana.

Uma pontuação mais alta indica maior probabilidade de que o valor extraído esteja correto. Você pode comparar as pontuações para extrair uma determinada entidade de documentos diferentes para identificar quais valores são mais ou menos confiáveis, e usá-los para criar uma lógica de processamento determinística, como limites, mecanismos de fallback e fluxos de trabalho Human-in-the-Loop.

{
  "response": {
    "name": "John Smith",
    "address": "123 Main St, San Francisco"
  },
  "scoring": {
    "scores": {
      "name": {
        "score": 0.95
      },
      "address": {
        "score": 0.82
      }
    }
  },
  "error": null
}

{
  "response": {
    "employees": ["Smith", "Johnson", "Doe"]
  },
  "scoring": {
    "scores": {
      "employees": {
        "score": 0.77
      }
    }
  },
  "error": null
}

{
  "response": {
    "income_table": {
      "month": ["February", "March", "April"],
      "income": ["$120 678", "$130 123", "$150 998"]
    }
  },
  "scoring": {
    "scores": {
      "income_table": {
        "score": 0.85
      }
    }
  },
  "error": null
}

SELECT AI_EXTRACT(
  file => TO_FILE('@db.schema.files', 'document.pdf'),
  responseFormat => {'name': 'What is the last name of the employee?', 'date': 'What is the inspection date?'},
  scores => TRUE
);

{
  "response": {
    "date": "2022-04-01",
    "name": "Johnson"
  },
  "scoring": {
    "scores": {
      "date": {
        "score": 0.96
      },
      "name": {
        "score": 0.99
      }
    }
  },
  "error": null
}

SELECT AI_EXTRACT(
  file => TO_FILE('@db.schema.files', 'agreement.pdf'),
  responseFormat => {
    'schema': {
      'type': 'object',
      'properties': {
        'buyer_list': {
          'description': 'What are the buyer names?',
          'type': 'array'
        }
      }
    }
  },
  scores => TRUE
);

{
  "response": {
    "buyer_list": [
      "John Davis",
      "Jane Davis"
    ]
  },
  "scoring": {
    "scores": {
      "buyer_list": {
        "score": 0.91
      }
    }
  },
  "error": null
}

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'
            }
          }
        }
      }
    }
  },
  scores => TRUE
);

{
  "response": {
    "income_table": {
      "income": ["$120 678", "$130 123", "$150 998"],
      "month": ["February", "March", "April"]
    }
  },
  "scoring": {
    "scores": {
      "income_table": {
        "score": 0.88
      }
    }
  },
  "error": null
}

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:

  Expand

  {'address': 'City, street, ZIP', 'name': 'First and last name'}
  

  Show lessSee more

  Scroll to top

• 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.

• As pontuações de extração opcionais estão disponíveis na versão preliminar quando você usa argumentos nomeados e passa scores => TRUE. Para obter mais detalhes, consulte Pontuações de extração (versão preliminar).

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 uso do parâmetro scale_factor altera a quantidade de tokens consumidos e a quantidade de páginas que podem ser processadas por chamada:

  • O número de tokens de entrada consumidos aumenta proporcionalmente a scale_factor.

  • O número máximo de páginas por documento que podem ser processadas por AI_EXTRACT diminui com scale_factor.

  Relacionamento de scale_factor com o número de tokens e páginas

  Valor scale_factor	Contagem de tokens por página	Número máx. de páginas por documento
  2	970 * 2 = 1940 tokens	125/2 = 62,5 (arredondado para 62)
  2.5	970 * 2,5 = 2425 tokens	125/2,5 = 50
  4	970 * 4 = 3880 tokens	125/4 = 31,25 (arredondado para 31)

  See moreShow less

  Expand

• 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:

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:

Exemplos¶

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'
        }
      }
    }
  }
);

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'
            }
          }
        }
      }
    }
  }
);

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'
        }
      }
    }
  }
);

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'
        }
      }
    }
  },
  config => {'scale_factor': 2.0}
);

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

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

SELECT AI_EXTRACT(
  model => 'db.schema.my_tuned_model',
  file => TO_FILE('@db.schema.files', 'invoice.pdf'),
  config => {'scale_factor': 2.0}
);

Avisos legais¶

Consulte AI e ML Snowflake para ver os avisos legais.