YepAPI/skills

OpenAI 통합

규칙

• 공식 openai 패키지 사용 — new OpenAI({ apiKey: process.env.OPENAI_API_KEY })
• 채팅 스트리밍: stream: true와 async iterator 사용 — 사용자 대상 응답에서는 전체 완료를 기다리지 않음
• 함수 호출: JSON Schema로 함수를 정의하고, 응답에서 tool_calls를 처리하며, 결과를 도구 메시지로 반환
• 구조화된 출력: response_format: { type: "json_schema", json_schema: {...} } 또는 AI SDK와 함께 Zod 사용
• 토큰 관리: 전송 전 토큰 추정 (문자당 약 4토큰), 제한 내에 맞추기 위해 컨텍스트 트리밍
• 모델 선택: 복잡한 추론에는 gpt-4o, 간단한 작업에는 gpt-4o-mini — 설정 가능하게 만들기
• 시스템 프롬프트를 첫 번째 메시지로 — 톤, 제약 조건 및 출력 형식 설정
• 온도: 결정적 출력(데이터 추출)에는 0, 창의적 작업에는 0.7-1.0
• 속도 제한: x-ratelimit-* 헤더 준수, 429 오류 시 지수 백오프 구현

패턴

// 스트리밍 완료
const stream = await openai.chat.completions.create({
  model: "gpt-4o",
  messages,
  stream: true,
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content || "";
  process.stdout.write(content);
}

// 함수 호출
const response = await openai.chat.completions.create({
  model: "gpt-4o",
  messages,
  tools: [{ type: "function", function: { name: "get_weather", parameters: schema } }],
});

피해야 할 것

• API 키 하드코딩 — 항상 환경 변수 사용
• 토큰 제한 무시 — 토큰을 계산하고 메시지를 사전에 트리밍
• 간단한 작업에 gpt-4o 사용 — 비용 절감을 위해 gpt-4o-mini 사용
• API 호출 시 오류 처리 누락 — 429, 500, 타임아웃 오류를 적절히 처리