-
Notifications
You must be signed in to change notification settings - Fork 1.4k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: new foundations section (#1948)
- Loading branch information
1 parent
a5c2845
commit 1af45ce
Showing
9 changed files
with
242 additions
and
102 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,44 @@ | ||
--- | ||
title: Overview | ||
description: An overview of foundational concepts critical to understanding the Vercel AI SDK | ||
--- | ||
|
||
# Overview | ||
|
||
<Note> | ||
This page is a beginner-friendly introduction to high-level artificial | ||
intelligence (AI) concepts. To dive right into implementing the Vercel AI SDK, | ||
feel free to skip ahead to our [quickstarts](/docs/getting-started) or learn | ||
about our [supported models and | ||
providers](/docs/foundations/providers-and-models). | ||
</Note> | ||
|
||
The Vercel AI SDK standardizes integrating artificial intelligence (AI) models across [supported providers](/docs/foundations/providers-and-models). This enables developers to focus on building great AI applications, not waste time on technical details. | ||
|
||
For example, here’s how you can generate text with various models using the Vercel AI SDK: | ||
|
||
<PreviewSwitchProviders /> | ||
|
||
To effectively leverage the AI SDK, it helps to familiarize yourself with the following concepts: | ||
|
||
## Generative Artificial Intelligence | ||
|
||
**Generative artificial intelligence** refers to models that predict and generate various types of outputs (such as text, images, or audio) based on what’s statistically likely, pulling from patterns they’ve learned from their training data. For example: | ||
|
||
- Given a photo, a generative model can generate a caption. | ||
- Given an audio file, a generative model can generate a transcription. | ||
- Given a text description, a generative model can generate an image. | ||
|
||
## Large Language Models | ||
|
||
A **large language model (LLM)** is a subset of generative models focused primarily on **text**. An LLM takes a sequence of words as input and aims to predict the most likely sequence to follow. It assigns probabilities to potential next sequences and then selects one. The model continues to generate sequences until it meets a specified stopping criterion. | ||
|
||
LLMs learn by training on massive collections of written text, which means they will be better suited to some use cases than others. For example, a model trained on GitHub data would understand the probabilities of sequences in source code particularly well. | ||
|
||
However, it's crucial to understand LLMs' limitations. When asked about less known or absent information, like the birthday of a personal relative, LLMs might "hallucinate" or make up information. It's essential to consider how well-represented the information you need is in the model. | ||
|
||
## Embedding Models | ||
|
||
An **embedding model** is used to convert complex data (like words or images) into a dense vector (a list of numbers) representation, known as an embedding. Unlike generative models, embedding models do not generate new text or data. Instead, they provide representations of semantic and synactic relationships between entities that can be used as input for other models or other natural language processing tasks. | ||
|
||
In the next section, you will learn about the difference between models providers and models, and which ones are available in the Vercel AI SDK. |
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,103 @@ | ||
--- | ||
title: Tools | ||
description: Learn about tools with the Vercel AI SDK. | ||
--- | ||
|
||
# Tools | ||
|
||
While [large language models (LLMs)](/docs/foundations/overview#large-language-models) have incredible generation capabilities, | ||
they struggle with discrete tasks (e.g. mathematics) and interacting with the outside world (e.g. getting the weather). | ||
|
||
Tools can be thought of as programs you give to a model which can be run as and when the model deems applicable. | ||
|
||
## What is a tool? | ||
|
||
A tool is an object that can be called by the model to perform a specific task. | ||
You can use tools with functions across the AI SDK (like [`generateText`](/docs/reference/ai-sdk-core/generate-text) or [`streamUI`](/docs/reference/ai-sdk-rsc/stream-ui)) by passing a tool(s) to the `tools` parameter. | ||
|
||
There are three elements of a tool, a description, parameters, and an optional `execute` or `generate` function (dependent on the SDK function). | ||
|
||
- **`description`**: An optional description of the tool that can influence when the tool is picked. | ||
- **`parameters`**: A [Zod schema](/docs/foundations/tools#schema-specification-and-validation-with-zod) that defines the parameters. It is converted to a JSON schema that is consumed by the LLM, and also used to validate the LLM tool calls. | ||
- **`execute`** or **`generate`**: An optional async or generator function that is called with the arguments from the tool call. | ||
|
||
## Tool Calls | ||
|
||
If the LLM decides to use a tool, it will generate a tool call. | ||
Tools with an `execute` or `generate` function are run automatically when these calls are generated. | ||
The results of the tool calls are returned using tool result objects. | ||
Each tool result object has a `toolCallId`, a `toolName`, a typed `args` object, and a typed `result`. | ||
|
||
## Tool Choice | ||
|
||
You can use the `toolChoice` setting to influence when a tool is selected. | ||
It supports the following settings: | ||
|
||
- `auto` (default): the model can choose whether and which tools to call. | ||
- `required`: the model must call a tool. It can choose which tool to call. | ||
- `none`: the model must not call tools | ||
- `{ type: 'tool', toolName: string (typed) }`: the model must call the specified tool | ||
|
||
```ts highlight="18" | ||
import { z } from 'zod'; | ||
import { generateText, tool } from 'ai'; | ||
|
||
const result = await generateText({ | ||
model: yourModel, | ||
tools: { | ||
weather: tool({ | ||
description: 'Get the weather in a location', | ||
parameters: z.object({ | ||
location: z.string().describe('The location to get the weather for'), | ||
}), | ||
execute: async ({ location }) => ({ | ||
location, | ||
temperature: 72 + Math.floor(Math.random() * 21) - 10, | ||
}), | ||
}), | ||
}, | ||
toolChoice: 'required', // force the model to call a tool | ||
prompt: | ||
'What is the weather in San Francisco and what attractions should I visit?', | ||
}); | ||
``` | ||
|
||
## Schema Specification and Validation with Zod | ||
|
||
Tool usage and structured object generation require the specification of schemas. | ||
The AI SDK uses [Zod](https://zod.dev/), the most popular JavaScript schema validation library, for schema specification and validation. | ||
|
||
You can install Zod with: | ||
|
||
<Tabs items={['pnpm', 'npm', 'yarn']}> | ||
<Tab> | ||
<Snippet text="pnpm install zod" dark /> | ||
</Tab> | ||
<Tab> | ||
<Snippet text="npm install zod" dark /> | ||
</Tab> | ||
<Tab> | ||
<Snippet text="yarn add zod" dark /> | ||
</Tab> | ||
</Tabs> | ||
|
||
You can then specify schemas, for example: | ||
|
||
```ts | ||
import z from 'zod'; | ||
|
||
const recipeSchema = z.object({ | ||
recipe: z.object({ | ||
name: z.string(), | ||
ingredients: z.array( | ||
z.object({ | ||
name: z.string(), | ||
amount: z.string(), | ||
}), | ||
), | ||
steps: z.array(z.string()), | ||
}), | ||
}); | ||
``` | ||
|
||
These schemas can be used to define parameters for tool calls and generated structured objects with [`generateObject`](/docs/reference/ai-sdk-core/generate-object) and [`streamObject`](/docs/reference/ai-sdk-core/stream-object). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,38 @@ | ||
--- | ||
title: Foundations | ||
description: A section that covers foundational knowledge around LLMs and concepts crucial to the Vercel AI SDK | ||
--- | ||
|
||
# Foundations | ||
|
||
<IndexCards | ||
cards={[ | ||
{ | ||
title: 'Overview', | ||
description: 'Learn about foundational concepts around AI and LLMs.', | ||
href: '/docs/foundations/overview', | ||
}, | ||
{ | ||
title: 'Providers and Models', | ||
description: | ||
'Learn about the providers and models that you can use with the Vercel AI SDK.', | ||
href: '/docs/foundations/providers-and-models', | ||
}, | ||
{ | ||
title: 'Prompts', | ||
description: | ||
'Learn about how Prompts are used and defined in the Vercel AI SDK.', | ||
href: '/docs/foundations/prompts', | ||
}, | ||
{ | ||
title: 'Tools', | ||
description: 'Learn about tools in the Vercel AI SDK.', | ||
href: '/docs/foundations/tools', | ||
}, | ||
{ | ||
title: 'Streaming', | ||
description: 'Learn why streaming is used for AI applications.', | ||
href: '/docs/ai-sdk-core/generating-structured-data', | ||
}, | ||
]} | ||
/> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.