`Output`
Output
Output 객체는 generateText와 streamText에서 구조화된 데이터 생성을 위한 출력 스펙을 제공합니다. 생성할 데이터의 예상 형태를 지정하고 검증을 자동으로 처리할 수 있게 해 줍니다.
출처: 문서
본문
import { generateText, Output } from 'ai';
__PROVIDER_IMPORT__;
import { z } from 'zod';
const { output } = await generateText({
model: __MODEL__,
output: Output.object({
schema: z.object({
name: z.string(),
age: z.number(),
}),
}),
prompt: 'Generate a user profile.',
});
Import
import { Output } from "ai"
Output Types (출력 유형)
Output.text()
일반 텍스트 생성을 위한 출력 스펙입니다. output을 지정하지 않았을 때의 기본 동작입니다.
import { generateText, Output } from 'ai';
const { output } = await generateText({
model: yourModel,
output: Output.text(),
prompt: 'Tell me a joke.',
});
// output is a string
Parameters (파라미터)
필요한 파라미터가 없습니다.
Returns (반환값)
스키마 검증 없이 일반 텍스트를 생성하는 Output<string, string> 스펙을 반환합니다.
Output.object()
스키마를 사용한 타입이 지정된 객체 생성을 위한 출력 스펙입니다. 출력은 타입 안전성을 보장하기 위해 제공된 스키마에 대해 검증됩니다.
import { generateText, Output } from 'ai';
import { z } from 'zod';
const { output } = await generateText({
model: yourModel,
output: Output.object({
schema: z.object({
name: z.string(),
age: z.number().nullable(),
labels: z.array(z.string()),
}),
}),
prompt: 'Generate information for a test user.',
});
// output matches the schema type
Parameters (파라미터)
schema:FlexibleSchema<OBJECT>— 생성할 객체의 구조를 정의하는 스키마입니다. Zod 스키마, Standard JSON 스키마, 커스텀 JSON 스키마를 지원합니다.name:string(선택) — 생성할 출력의 선택적 이름입니다. 일부 프로바이더가 툴 또는 스키마 이름을 통한 추가 LLM 안내에 사용합니다.description:string(선택) — 생성할 출력의 선택적 설명입니다. 일부 프로바이더가 툴 또는 스키마 설명을 통한 추가 LLM 안내에 사용합니다.
Returns (반환값)
다음과 같은 Output<OBJECT, DeepPartial<OBJECT>> 스펙을 반환합니다.
- 완전한 출력은 스키마에 대해 완전히 검증됨
- 부분 출력(스트리밍 중)은 스키마 유형의 깊은 부분(deep partial) 버전
Output.array()
타입이 지정된 요소들의 배열을 생성하기 위한 출력 스펙입니다. 각 요소는 제공된 요소 스키마에 대해 검증됩니다.
import { generateText, Output } from 'ai';
import { z } from 'zod';
const { output } = await generateText({
model: yourModel,
output: Output.array({
element: z.object({
location: z.string(),
temperature: z.number(),
condition: z.string(),
}),
minItems: 2,
maxItems: 2,
}),
prompt: 'List the weather for San Francisco and Paris.',
});
// output is an array of weather objects
Parameters (파라미터)
element:FlexibleSchema<ELEMENT>— 각 배열 요소의 구조를 정의하는 스키마입니다. Zod 스키마, Valibot 스키마 또는 JSON 스키마를 지원합니다.minItems:number(선택) — 생성할 최소 요소 수입니다. 음이 아닌 정수여야 합니다.maxItems:number(선택) — 생성할 최대 요소 수입니다. 음이 아닌 정수이면서minItems보다 크거나 같아야 합니다.name:string(선택) — 생성할 출력의 선택적 이름입니다. 일부 프로바이더가 툴 또는 스키마 이름을 통한 추가 LLM 안내에 사용합니다.description:string(선택) — 생성할 출력의 선택적 설명입니다. 일부 프로바이더가 툴 또는 스키마 설명을 통한 추가 LLM 안내에 사용합니다.
Returns (반환값)
다음과 같은 Output<Array<ELEMENT>, Array<ELEMENT>> 스펙을 반환합니다.
- 완전한 출력은 모든 요소가 검증된 배열
- 완전한 출력은
minItems와maxItems에 대해 검증됨 - 부분 출력은 완전히 검증된 요소만 포함 (불완전한 요소는 제외)
정확한 요소 수를 요구하려면 minItems와 maxItems를 같은 값으로 설정하세요. 프로바이더가 지원하면 경계는 프로바이더 측 스키마에 포함됩니다. AI SDK도 완성된 출력을 검증하므로, 이러한 스키마 키워드를 무시하는 프로바이더도 범위를 벗어난 결과를 반환할 수 없습니다.
elementStream으로 스트리밍
streamText를 Output.array()와 함께 사용하면, 요소가 생성될 때 elementStream으로 순회할 수 있습니다.
import { streamText, Output } from 'ai';
import { z } from 'zod';
const { elementStream } = streamText({
model: yourModel,
output: Output.array({
element: z.object({
name: z.string(),
class: z.string(),
description: z.string(),
}),
}),
prompt: 'Generate 3 hero descriptions for a fantasy role playing game.',
});
for await (const hero of elementStream) {
console.log(hero); // Each hero is complete and validated
}
Output.choice()
미리 정의된 문자열 옵션 집합에서 선택하기 위한 출력 스펙입니다. 분류 작업이나 고정 열거형 답변에 유용합니다.
import { generateText, Output } from 'ai';
const { output } = await generateText({
model: yourModel,
output: Output.choice({
options: ['sunny', 'rainy', 'snowy'] as const,
}),
prompt: 'Is the weather sunny, rainy, or snowy today?',
});
// output is 'sunny' | 'rainy' | 'snowy'
Parameters (파라미터)
options:Array<CHOICE>— 모델이 선택할 수 있는 문자열 옵션 배열입니다. 출력은 이 값 중 정확히 하나가 됩니다.name:string(선택) — 생성할 출력의 선택적 이름입니다. 일부 프로바이더가 툴 또는 스키마 이름을 통한 추가 LLM 안내에 사용합니다.description:string(선택) — 생성할 출력의 선택적 설명입니다. 일부 프로바이더가 툴 또는 스키마 설명을 통한 추가 LLM 안내에 사용합니다.
Returns (반환값)
다음과 같은 Output<CHOICE, CHOICE> 스펙을 반환합니다.
- 완전한 출력은 제공된 옵션 중 정확히 하나인지 검증됨
Output.json()
구조화되지 않은 JSON 생성을 위한 출력 스펙입니다. 특정 스키마를 강제하지 않고 임의의 JSON을 생성하려 할 때 사용하세요.
import { generateText, Output } from 'ai';
const { output } = await generateText({
model: yourModel,
output: Output.json(),
prompt:
'For each city, return the current temperature and weather condition as a JSON object.',
});
// output is any valid JSON value
Parameters (파라미터)
name:string(선택) — 생성할 출력의 선택적 이름입니다. 일부 프로바이더가 툴 또는 스키마 이름을 통한 추가 LLM 안내에 사용합니다.description:string(선택) — 생성할 출력의 선택적 설명입니다. 일부 프로바이더가 툴 또는 스키마 설명을 통한 추가 LLM 안내에 사용합니다.
Returns (반환값)
다음과 같은 Output<JSONValue, JSONValue> 스펙을 반환합니다.
- 출력이 유효한 JSON인지 검증
- 특정 구조는 강제하지 않음
Error Handling (오류 처리)
구조화된 출력으로 generateText가 유효한 객체를 생성하지 못하면 NoObjectGeneratedError를 발생시킵니다.
import { generateText, Output, NoObjectGeneratedError } from 'ai';
try {
await generateText({
model: yourModel,
output: Output.object({ schema }),
prompt: 'Generate a user profile.',
});
} catch (error) {
if (NoObjectGeneratedError.isInstance(error)) {
console.log('NoObjectGeneratedError');
console.log('Cause:', error.cause);
console.log('Text:', error.text);
console.log('Response:', error.response);
console.log('Usage:', error.usage);
}
}