ai
Version:
AI SDK by Vercel - build apps like ChatGPT, Claude, Gemini, and more with a single interface for any model using the Vercel AI Gateway or go direct to OpenAI, Anthropic, Google, or any other model provider.
67 lines (52 loc) • 5.85 kB
text/mdx
---
title: experimental_extract
description: Extract typed field values from shared state with an extraction model.
---
# `experimental_extract()`
```ts
import { experimental_extract } from 'ai';
```
Extracts a nonempty map of typed fields from one state. See
[Extractions](/docs/ai-sdk-core/extractions) for examples and semantics.
## Parameters
| Parameter | Type | Description |
| ----------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `model` | `Experimental_ExtractionModel` | Required experimental v4 extraction model instance. |
| `state` | `Experimental_ExtractionState` | Required string, JSON object, or ordered array of text, file, and JSON parts. |
| `fields` | `Record<string, Experimental_ExtractionField>` | Required nonempty field map. |
| `referenceDate` | `string` | Optional `YYYY-MM-DD` date that anchors relative dates. |
| `maxOutputTokens` | `number` | Optional maximum output tokens, an integer >= 1. |
| `reasoning` | `'provider-default' \| 'none' \| 'minimal' \| 'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'` | Optional reasoning effort for supported models. |
| `maxRetries` | `number` | Nonnegative integer; defaults to 2. |
| `abortSignal` | `AbortSignal` | Cancels the extraction request. |
| `experimental_download` | `Experimental_DownloadFunction` | Required for remote file URLs in state. Use `createDownload({ fetch })` with a DNS-protected transport for untrusted URLs. |
| `headers` | `Record<string, string>` | Additional HTTP headers. |
| `providerOptions` | `ProviderOptions` | Provider-specific options. |
Remote file URLs are rejected with `DownloadError` unless `experimental_download`
is supplied. The model's `fetch` option does not apply to these downloads. See
[Secure URL Fetching](/docs/advanced/secure-url-fetching#core-file-downloads).
## Fields
| Type | Options |
| ---------- | ------------------------------------------------------------------------------------------------- |
| `text` | None |
| `number` | `unit`, `integer`, `decimals` (0 to 6) |
| `date` | None |
| `time` | None |
| `datetime` | None |
| `duration` | `unit` (`seconds`, `minutes`, `hours`, `days`, `weeks`, `months`, `years`), `integer`, `decimals` |
| `list` | Required `items` (`text`, `number`, or `date`), `integer`, `decimals` |
Every field accepts optional `instructions` as a string, JSON object, or JSON
array. See [field types](/docs/ai-sdk-core/extractions#field-types).
## Result
Returns `Promise<Experimental_ExtractionResult<FIELDS>>`:
- `answers`: One typed answer per field ID, with `value` typed from the field.
- `usage`: `inputTokens`, `outputTokens`, and `totalTokens`, each possibly undefined.
- `warnings`: Provider warnings, also passed to the SDK warning logger.
- `providerMetadata`: Optional provider-specific metadata.
- `response`: Timestamp, model ID, and optional response ID, headers, and body.
## Errors
Unsupported field types throw `Experimental_ExtractionUnsupportedFieldTypeError`
before provider I/O. Invalid inputs throw `InvalidArgumentError`; malformed
answers throw `InvalidResponseDataError`. Fields the model refuses throw
`Experimental_ExtractionRefusalError`. Model instances must implement v4; other
versions throw `UnsupportedModelVersionError`.