Skip to content

Commit 4c00e47

Browse files
atierianatierian
authored
add initial generation route page (#7959)
1 parent be470e0 commit 4c00e47

File tree

2 files changed

+165
-0
lines changed

2 files changed

+165
-0
lines changed

‎src/pages/[platform]/build-a-backend/ai/generation/index.mdx‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,3 +32,167 @@ export function getStaticProps(context) {
3232
Amplify AI sections are under construction
3333

3434
</Callout>
35+
36+
37+
AI generation routes are a request-response API used to generate structured output from AI models. Examples of generation routes include:
38+
- generated structured data from unstructured input.
39+
- summarization.
40+
41+
Under the hood, a generation route is an AppSync query that ensures the AI model responds with the response type defined for the route.
42+
43+
## Generate Typed Objects
44+
45+
```ts title="Schema Definition"
46+
const schema = a.schema({
47+
generateRecipe: a.generation({
48+
aiModel: a.ai.model('Claude 3 Haiku'),
49+
systemPrompt: 'You are a helpful assistant that generates recipes.',
50+
})
51+
.arguments({ description: a.string() })
52+
.returns(
53+
a.customType({
54+
name: a.string(),
55+
ingredients: a.string().array(),
56+
instructions: a.string(),
57+
})
58+
)
59+
.authorization((allow) => allow.authenticated())
60+
});
61+
```
62+
63+
```ts title="Data Client Request"
64+
const description = 'I would like to bake a birthday cake for my friend. She has celiac disease and loves chocolate.'
65+
const { data, errors } = await client.generations
66+
.generateRecipe({ description })
67+
68+
/**
69+
Example response:
70+
{
71+
"name": "Gluten-Free Chocolate Birthday Cake",
72+
"ingredients": [
73+
"gluten-free all-purpose flour",
74+
"cocoa powder",
75+
"granulated sugar",
76+
"baking powder",
77+
"baking soda",
78+
"salt",
79+
"eggs",
80+
"milk",
81+
"vegetable oil",
82+
"vanilla extract"
83+
],
84+
"instructions": "1. Preheat oven to 350°F. Grease and flour two 9-inch round baking pans.\n2. In a medium bowl, whisk together the gluten-free flour, cocoa powder, sugar, baking powder, baking soda and salt.\n3. In a separate bowl, beat the eggs. Then add the milk, oil and vanilla and mix well.\n4. Gradually add the wet ingredients to the dry ingredients and mix until just combined. Do not over mix.\n5. Divide the batter evenly between the prepared pans.\n6. Bake for 30-35 minutes, until a toothpick inserted in the center comes out clean.\n7. Allow cakes to cool in pans for 10 minutes, then transfer to a wire rack to cool completely.\n8. Frost with your favorite gluten-free chocolate frosting."
85+
}
86+
*/
87+
```
88+
89+
## Generate Scalar Types
90+
91+
```ts title="Schema Definition"
92+
const schema = ({
93+
summarize: a.generation({
94+
aiModel: a.ai.model('Claude 3 Haiku'),
95+
systemPrompt: 'Provide an accurate, clear, and concise summary of the input provided'
96+
})
97+
.arguments({ input: a.string() })
98+
.returns(a.string())
99+
.authorization((allow) => allow.guest()),
100+
});
101+
```
102+
103+
```ts title="Data Client Request"
104+
const { data: summary, errors } = await client.generations
105+
.summarize({ input })
106+
```
107+
108+
## Setting Inference Parameters
109+
110+
You can influence response generation by setting inference parameters for the AI model.
111+
This ability to control the randomness and diversity of responses is useful for generating responses that are tailored to your needs.
112+
For more information on inference parameters, see [Amazon Bedrock > Inference Parameters](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-parameters.html).
113+
```ts title="Inference Parameters"
114+
const schema = a.schema({
115+
generateHaiku: a.generation({
116+
aiModel: a.ai.model('Claude 3 Haiku'),
117+
systemPrompt: 'You are a helpful assistant that generates haikus.',
118+
// highlight-start
119+
inferenceConfiguration: {
120+
maxTokens: 1000,
121+
temperature: 0.5,
122+
topP: 0.9,
123+
}
124+
// highlight-end
125+
}),
126+
});
127+
```
128+
129+
## Limitations
130+
131+
### 1. Generation routes do not support referencing models
132+
133+
For example, the following schema defines a `Recipe` model, but this model cannot be used as the return type of a generation route.
134+
135+
```ts title="Invalid Model Reference"
136+
const schema = a.schema({
137+
Recipe: a.model({
138+
name: a.string(),
139+
ingredients: a.string().array(),
140+
instructions: a.string(),
141+
}),
142+
generateRecipe: a.generation({
143+
aiModel: a.ai.model('Claude 3 Haiku'),
144+
systemPrompt: 'You are a helpful assistant that generates recipes.',
145+
})
146+
.arguments({ description: a.string() })
147+
.returns(a.ref('Recipe')) // ❌ Invalid
148+
.authorization((allow) => allow.authenticated()),
149+
});
150+
```
151+
152+
You can, however, reference custom types. Here's an example of a custom type that can be used as the return type of a generation route.
153+
```ts title="Valid Custom Type Reference"
154+
const schema = a.schema({
155+
Recipe: a.customType({
156+
name: a.string(),
157+
ingredients: a.string().array(),
158+
instructions: a.string(),
159+
}),
160+
generateRecipe: a.generation({
161+
aiModel: a.ai.model('Claude 3 Haiku'),
162+
systemPrompt: 'You are a helpful assistant that generates recipes.',
163+
})
164+
.arguments({ description: a.string() })
165+
.returns(a.ref('Recipe')) // ✅ Valid
166+
.authorization((allow) => allow.authenticated()),
167+
});
168+
```
169+
170+
### 2. Generation routes do not support some required types.
171+
172+
The following AppSync scalar types are not supported as **required** fields in response types:
173+
- `AWSEmail`
174+
- `AWSDate`
175+
- `AWSTime`
176+
- `AWSDateTime`
177+
- `AWSTimestamp`
178+
- `AWSPhone`
179+
- `AWSURL`
180+
- `AWSIPAddress`
181+
182+
```ts title="Unsupported Required Type"
183+
const schema = a.schema({
184+
generateUser: a.generation({
185+
aiModel: a.ai.model('Claude 3 Haiku'),
186+
systemPrompt: 'You are a helpful assistant that generates users.',
187+
})
188+
.arguments({ description: a.string() })
189+
.returns(
190+
a.customType({
191+
name: a.string(),
192+
email: a.email().required(), // ❌ Required field with unsupported type
193+
dateOfBirth: a.date().required(), // ❌ Required field with unsupported type
194+
})
195+
)
196+
.authorization((allow) => allow.authenticated()),
197+
});
198+

‎src/pages/[platform]/build-a-backend/ai/set-up-ai/index.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ With Amplify AI, you can define Conversation and Generation routes backed by an
4747

4848
## Building your AI backend
4949

50+
5051
If you've run `npm create amplify@latest` already, you should see an `amplify/data/resource/ts` file, which is the central location to configure your AI backend. Within the `schema` object, you define Conversation routes (`a.conversation({})`) and Generation routes (`a.generation({})`), and can integrate them seamlessly with existing Amplify Data schema objects.
5152

5253
```ts title="amplify/data/resources.ts"

0 commit comments

Comments
 (0)