`useObject()`

useObject()

백엔드의 streamText와 Output.object()로 생성한 스트리밍 JSON 객체를 소비하는 훅을 설명하는 문서예요.

출처: 문서

본문

참고: useObject는 React, Svelte, Vue에서만 사용할 수 있어요.

JSON 객체를 나타내는 텍스트 스트림을 소비하고, 스키마에 따라 완전한 객체로 파싱할 수 있게 해 줘요. 백엔드에서 streamText와 Output.object()와 함께 사용할 수 있어요.

'use client';

import { useObject } from '@ai-sdk/react';

export default function Page() {
  const { object, submit } = useObject({
    api: '/api/use-object',
    schema: z.object({ content: z.string() }),
  });

  return (
    <div>
      <button onClick={() => submit('example input')}>Generate</button>
      {object?.content && <p>{object.content}</p>}
    </div>
  );
}

Import

  • React: import { useObject } from '@ai-sdk/react'
  • Svelte: import { StructuredObject } from '@ai-sdk/svelte'
  • Vue: import { useObject } from '@ai-sdk/vue'

API 시그니처 (API Signature)

매개변수 (Parameters)

이름 타입 설명
api string 객체를 생성하도록 호출되는 API 엔드포인트예요. 스키마와 일치하는 JSON을 청크 텍스트로 스트리밍해야 해요. 상대 경로(/로 시작) 또는 절대 URL일 수 있어요.
schema Zod Schema | JSON Schema 완전한 객체의 형태를 정의하는 스키마예요. Zod 스키마 또는 JSON 스키마(jsonSchema 함수 사용)를 전달할 수 있어요.
id? string 고유 식별자예요. 제공하지 않으면 임의의 값이 생성돼요. 제공하면 같은 id를 가진 useObject 훅이 컴포넌트 간에 상태를 공유해요.
initialValue (선택) DeepPartial<RESULT> | undefined 초기 객체의 값이에요. 선택 사항이에요.
fetch (선택) FetchFunction API 호출에 사용할 커스텀 fetch 함수예요. 기본값은 전역 fetch 함수예요. 선택 사항이에요.
headers (선택) Record<string, string> | Headers API 엔드포인트에 전달할 헤더 객체예요. 선택 사항이에요.
credentials (선택) RequestCredentials fetch 요청에 사용할 자격 증명 모드예요. 가능한 값: "omit", "same-origin", "include". 선택 사항이에요.
onError (선택) (error: Error) => void 오류가 발생했을 때 호출되는 콜백 함수예요. 선택 사항이에요.
onFinish (선택) (result: OnFinishResult) => void 스트리밍 응답이 끝났을 때 호출돼요.
onFinish.object T | undefined 생성된 객체예요 (스키마에 따라 타입이 정해짐). 최종 객체가 스키마와 일치하지 않으면 undefined일 수 있어요.
onFinish.error Error | undefined 선택적 오류 객체예요. 예를 들어 최종 객체가 스키마와 일치하지 않으면 TypeValidationError예요.

반환값 (Returns)

이름 타입 설명
submit (input: INPUT) => void 제공된 입력을 JSON 본문으로 API를 호출해요.
object DeepPartial<RESULT> | undefined 생성된 객체의 현재 값이에요. API가 JSON 청크를 스트리밍할 때 업데이트돼요.
error Error | undefined API 호출이 실패하면 오류 객체예요.
isLoading boolean 요청이 현재 진행 중인지 나타내는 불리언 플래그예요.
stop () => void 현재 API 요청을 중단하는 함수예요.
clear () => void 객체 상태를 비우는 함수예요.

예제 (Examples)

더 알아보기 (Learn more)