> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tela.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Dividir, Recortar e Mapear

> Quebre documentos em páginas ou partes, mantenha só algumas páginas e repita etapas para cada item de uma lista

Documentos longos ou agrupados são mais fáceis de processar em pedaços. **Dividir** e **Recortar** (grupo **Recursos**) transformam um arquivo em vários, e **Mapear** repete um grupo de etapas uma vez por item de uma lista, em paralelo, e depois entrega a lista de resultados.

Na segunda variante do exemplo desta seção, um contrato de 60 páginas é **Dividido** em páginas, um **Mapear** roda **Extract Page** para cada página, e uma etapa de **Execução de Código** junta as páginas em um registro só.

![Workflow com uma etapa Dividir PDF, um Mapear com Extract Page dentro e uma etapa de Execução de Código](https://mintcdn.com/meistrari/M2w7BduKZAFA1Sbx/images/pt/workflow/pages-graph.png?fit=max\&auto=format\&n=M2w7BduKZAFA1Sbx\&q=85\&s=afe27f313994776dbdad2adc2d586c52)

## Dividir

**Dividir** recebe um PDF ou CSV e devolve uma **lista de arquivos**, um por pedaço.

**1. Escolha o arquivo**

Em **Arquivo**, digite `@` e escolha a Entrada de arquivo ou a saída de arquivo de uma etapa anterior (por exemplo o resultado de um Recortar). Dividir aceita um arquivo ou uma lista de arquivos.

**2. Escolha o tipo**

**PDF** ou **CSV**.

**3. Escolha o Modo de divisão (PDF)**

* **Páginas Únicas** (determinístico): cada página vira o próprio arquivo. Você pode definir quantas páginas entram em cada pedaço; com 1, cada página é um arquivo separado.
* **Arquivos Inteligentes** (IA): o modelo detecta sub-documentos lógicos e agrupa páginas em arquivos, por exemplo um pacote que contém um contrato, os anexos e uma carta de apresentação.

**4. Se quiser, adicione instruções personalizadas (Arquivos Inteligentes)**

**Instruções personalizadas** dizem à IA como agrupar as páginas ("Agrupe as páginas por número da fatura; mantenha as cartas de apresentação com seus contratos"). Escolha **Sempre** para aplicá-las a todos os arquivos, ou **Somente quando não houver sumário** para usá-las só como alternativa.

### O que Dividir devolve

Uma lista, com um item por pedaço:

| Campo | Significado |
| - | - |
| `file` | o novo arquivo deste pedaço |
| `originalFile` | o arquivo de onde ele foi cortado |
| `pages` | a faixa de páginas, como `"1"`, `"3-5"` ou `"1,2,5-10"` |
| `startPage`, `endPage` | primeira e última página do pedaço |
| `description`, `fileType` | o que a IA entendeu que o pedaço é; preenchidos só no modo Arquivos Inteligentes |

Os itens são arquivos, não texto. Para lê-los, passe-os a um Módulo de IA (uma por vez dentro de um Mapear, usada como Parser ou Multimodal) ou a outra etapa de documento.

## Recortar

**Recortar** mantém só algumas páginas de um PDF.

**1. Escolha o arquivo**

**Use esta variável**: digite `@` e escolha o arquivo.

**2. Escolha as páginas**

**E recorte com este valor**: números e faixas de páginas, contadas a partir de 1, como `1-2, 7, 10-18`.

Recortar devolve uma lista com um item por arquivo de entrada: `file` (o PDF recortado), `originalFile` e os `indexes` que você pediu. Uso típico: manter as duas primeiras páginas de cada contrato antes da extração, para que o modelo leia só a capa e o resumo dos termos.

> [!TIP]
>
> Encadeie Recortar e Dividir: Recorte as páginas de assinatura de um pacote, depois Divida o resultado em páginas únicas para uma checagem por página.

## Mapear

**Mapear** repete as etapas que você coloca dentro dele para **cada item de uma lista**, roda essas iterações em paralelo e devolve a lista de resultados.

**1. Adicione o Mapear**

Adicione **Mapear** depois da etapa que produz a lista (um Dividir, ou um Módulo de IA cujo Formato de Saída tem um atributo de lista). Dê um nome, por exemplo `Each page`.

**2. Escolha sobre o que iterar**

**Iterar sobre**: digite `@` e escolha a lista. No exemplo, a saída de **Split contract**.

**3. Dê nome à Variável de Map**

**Variável de Map** é o nome do item atual dentro do Mapear, por exemplo `page`. As etapas dentro do Mapear a referenciam como `@page`.

**4. Adicione etapas dentro do Mapear**

Clique dentro do Mapear para adicionar as etapas que rodam para cada item. No exemplo, **Extract Page** é um Módulo de IA cujo prompt lê `@page` (usada como Multimodal, para um contrato digitalizado) e devolve `page_number`, `clauses` e `amounts`.

![Configuração do Mapear com a lista e a variável do Map, e o aviso de que a etapa interna está dentro de um nó Map](https://mintcdn.com/meistrari/M2w7BduKZAFA1Sbx/images/pt/workflow/map-config.png?fit=max\&auto=format\&n=M2w7BduKZAFA1Sbx\&q=85\&s=52ac3d6fd0eb69636d58a70c6bd1f4f5)

Dentro do Mapear, uma etapa vê a Variável de Map, as Entradas do Workflow e as saídas das etapas anteriores ao Mapear. Um aviso em cada etapa interna lembra a qual Mapear ela pertence.

### O que Mapear devolve

Depois do Mapear, as etapas seguintes veem:

* a **etapa Mapear** em si: uma lista com uma posição por item, cada uma contendo as saídas das etapas internas, cujas chaves são os nomes das etapas;
* cada **etapa interna**: uma lista com as saídas daquela etapa, uma por item, na mesma ordem da lista de entrada.

Então, depois de `Each page`, referenciar **Extract Page** dá a lista de registros das páginas. Na Execução de Código isso é `input["Extract Page"]`, um array que você pode juntar:

```javascript theme={null}
// Merge the per-page extractions of the Each page Map into one record.
async function execute(input) {
  const pages = input["Extract Page"]
  return {
    page_count: pages.length,
    clauses: pages.flatMap(p => p.clauses ?? []),
    total_of_amounts: pages.reduce((sum, p) => sum + (p.amounts ?? []).reduce((s, a) => s + a, 0), 0),
  }
}
```

Se a lista estiver vazia, o Mapear devolve uma lista vazia e o Workflow continua na próxima etapa.

### Lendo os resultados do Mapear

No painel de resultado, um Mapear mostra a contagem de iterações e permite navegar entre elas (**Iteração 3 de 60**) para ver as saídas e os erros de cada item. Em **Depurar**, cada iteração é uma execução filha própria: abra **Iterações** e **Abrir iteração como execução** para inspecionar uma página como se fosse uma execução independente. Pela API, as etapas internas trazem uma entrada em `runs` por iteração; veja [Saídas e resultados](https://docs.tela.com/pt/workflow/outputs-and-results.md#pela-api).

> [!NOTE]
>
> As iterações rodam em paralelo, então um Mapear sobre 60 páginas termina mais ou menos no tempo de uma página, mas também faz 60 chamadas ao modelo de uma vez. Fique de olho nas cotas e no custo do modelo ao mapear documentos grandes.

## Padrões comuns

> **Extração por página de um documento longo**
>
> **Dividir** (Páginas Únicas, 1 página) → **Mapear** sobre a saída do Dividir → dentro: **Módulo de IA** lendo `@page` → depois do Mapear: **Execução de Código** juntando `input["<etapa interna>"]`, ou um **Módulo de IA** que recebe a lista inteira (usada como Parser) e consolida.

> **Um pacote, vários documentos**
>
> **Dividir** no modo **Arquivos Inteligentes** com instruções como "Separe o contrato principal de cada anexo" → **Mapear** sobre os pedaços → dentro: **Classificação** ou **Módulo de IA** por pedaço. Use `description` e `fileType` de cada pedaço para decidir o que fazer com ele.

> **Lotes: vários arquivos em uma Entrada**
>
> Uma Entrada de arquivo pode receber vários arquivos. Passe-a direto ao **Mapear** (**Iterar sobre** = a Entrada) para rodar as mesmas etapas para cada contrato enviado, ou ao **Dividir** antes para obter as páginas de todos eles.

> **Só as páginas que importam**
>
> **Recortar** páginas `1-2` → **Módulo de IA** sobre o arquivo recortado. Mais barato e mais preciso do que enviar o documento inteiro quando a informação está sempre no mesmo lugar.

> **Iterar sobre itens extraídos, não sobre páginas**
>
> Um **Módulo de IA** devolve um atributo de lista (`line_items`) → **Mapear** sobre `Extract Data › line_items` → dentro: um **Canvas Existente** que valida um item. Listas de Formatos de Saída são entradas válidas de Mapear, não só arquivos.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.