오류 처리와 경고

오류 처리와 경고 (Error Handling and Warnings)

AI SDK UI는 브라우저에서 예상대로 동작하지 않을 수 있는 상황에 대한 경고(warning)와, UI 훅이 반환하는 error 객체를 통한 오류 처리를 함께 제공합니다. 경고는 문제가 오류가 되기 전에 고칠 수 있게 도와주며, 오류는 사용자에게 안전한 메시지로 보여주고 재시도 흐름을 구성하는 것이 권장됩니다.

출처: 공식문서

본문

경고

AI SDK는 뭔가 예상대로 동작하지 않을 수 있을 때 경고를 보여줍니다. 이 경고는 문제가 오류가 되기 전에 고치는 데 도움이 됩니다.

경고가 나타나는 경우

브라우저 콘솔에 경고가 표시되는 때:

지원되지 않는 기능: AI 모델이 지원하지 않는 기능이나 설정(특정 옵션·파라미터 등)을 사용할 때.
호환성 경고: 기능이 호환성 모드로 사용될 때. 의도한 것과 다르거나 덜 최적으로 동작할 수 있습니다.
기타 경고: AI 모델이 일반적인 문제나 권고 메시지 같은 다른 유형의 이슈를 보고할 때.

경고 메시지

모든 경고는 "AI SDK Warning:"으로 시작해 쉽게 찾을 수 있습니다. 예:

AI SDK Warning: The feature "temperature" is not supported by this model

경고 끄기

기본적으로 경고는 콘솔에 표시됩니다. 이 동작을 제어할 수 있습니다:

모든 경고 끄기

전역 변수를 설정해 경고를 완전히 끌 수 있습니다:

globalThis.AI_SDK_LOG_WARNINGS = false;

커스텀 경고 핸들러

경고를 처리하는 자신만의 함수를 제공할 수도 있습니다. 프로바이더 id, 모델 id, 경고 목록을 받습니다.

globalThis.AI_SDK_LOG_WARNINGS = ({ warnings, provider, model }) => {
  // Handle warnings your own way
};

오류 처리

오류 헬퍼 객체

각 AI SDK UI 훅은 UI에 오류를 렌더링하는 데 쓸 수 있는 error 객체도 반환합니다. error 객체로 오류 메시지를 보여주거나, 제출 버튼을 비활성화하거나, 재시도 버튼을 보여줄 수 있습니다.

사용자에게는 "Something went wrong." 같은 일반적인 오류 메시지를 보여주는 것을 권장합니다. 서버 정보가 새는 것을 막는 좋은 관행입니다.

'use client';

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

export default function Chat() {
  const [input, setInput] = useState('');
  const { messages, sendMessage, error, regenerate } = useChat();

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    sendMessage({ text: input });
    setInput('');
  };

  return (
    <div>
      {messages.map(m => (
        <div key={m.id}>
          {m.role}:{' '}
          {m.parts
            .filter(part => part.type === 'text')
            .map(part => part.text)
            .join('')}
        </div>
      ))}

      {error && (
        <>
          <div>An error occurred.</div>
          <button type="button" onClick={() => regenerate()}>
            Retry
          </button>
        </>
      )}

      <form onSubmit={handleSubmit}>
        <input
          value={input}
          onChange={e => setInput(e.target.value)}
          disabled={error != null}
        />
      </form>
    </div>
  );
}

대안: 실패한 메시지 교체

실패한 사용자 메시지를 새 입력으로 교체하는 커스텀 제출 핸들러를 작성할 수도 있습니다. 오류 전에 어시스턴트 응답이 스트리밍을 시작했다면 부분 어시스턴트 응답과 그 사용자 메시지를 모두 제거하세요.

'use client';

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

export default function Chat() {
  const [input, setInput] = useState('');
  const { sendMessage, error, messages, setMessages } = useChat();

  function customSubmit(event: React.FormEvent<HTMLFormElement>) {
    event.preventDefault();

    if (error != null) {
      setMessages(messages =>
        messages.at(-1)?.role === 'assistant'
          ? messages.slice(0, -2)
          : messages.slice(0, -1),
      );
    }

    sendMessage({ text: input });
    setInput('');
  }

  return (
    <div>
      {messages.map(m => (
        <div key={m.id}>
          {m.role}:{' '}
          {m.parts
            .filter(part => part.type === 'text')
            .map(part => part.text)
            .join('')}
        </div>
      ))}

      {error && <div>An error occurred.</div>}

      <form onSubmit={customSubmit}>
        <input value={input} onChange={e => setInput(e.target.value)} />
      </form>
    </div>
  );
}

오류 처리 콜백

useChat이나 useCompletion 훅의 옵션으로 onError 콜백 함수를 전달해 오류를 처리할 수 있습니다. 콜백 함수는 오류 객체를 인자로 받습니다.

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

export default function Page() {
  const {
    /* ... */
  } = useChat({
    // handle error:
    onError: error => {
      console.error(error);
    },
  });
}

테스트용 오류 주입

테스트를 위해 오류를 만들고 싶을 수 있습니다. 라우트 핸들러에서 오류를 던지면 쉽게 만들 수 있습니다:

export async function POST(req: Request) {
  throw new Error('This is a test error');
}

오류 처리와 경고