[G1-Sync] Manual knowledge update
This commit is contained in:
Antigravity Agent
@@ -2,89 +2,220 @@
|
||||
id: wiki-2026-0508-openai-api-integration
|
||||
title: OpenAI API Integration
|
||||
category: 10_Wiki/Topics
|
||||
status: needs_review
|
||||
status: verified
|
||||
canonical_id: self
|
||||
aliases: [AI-OPENAI-API-001]
|
||||
aliases: [OpenAI API, GPT API, OpenAI SDK Integration]
|
||||
duplicate_of: none
|
||||
source_trust_level: A
|
||||
confidence_score: 1.0
|
||||
tags: [ai, openai, api, llm, integration, development, gpt-4]
|
||||
confidence_score: 0.92
|
||||
verification_status: applied
|
||||
tags: [openai, api, gpt, function-calling, structured-output, vision, audio, batch, embeddings]
|
||||
raw_sources: []
|
||||
last_reinforced: 2026-04-26
|
||||
last_reinforced: 2026-05-10
|
||||
github_commit: pending
|
||||
inferred_by: Claude Opus 4.7 (auto-normalize 2026-05-08)
|
||||
tech_stack:
|
||||
language: unspecified
|
||||
framework: unspecified
|
||||
tech_stack: { language: python/typescript, framework: openai-sdk }
|
||||
---
|
||||
|
||||
# OpenAI API Integration (OpenAI API 통합)
|
||||
# OpenAI API Integration
|
||||
|
||||
## 📌 한 줄 통찰 (The Karpathy Summary)
|
||||
> "거대 모델의 지능을 단 몇 줄의 API 호출로 내 서비스의 심장에 이식하고, 기계와 인간의 대화를 비즈니스 가치로 변환하라" — OpenAI가 제공하는 최첨단 AI 모델(GPT, DALL-E, Whisper 등)을 외부 애플리케이션에 연결하여 텍스트 생성, 분석, 이미지 처리 등의 기능을 구현하는 개발 인터페이스.
|
||||
OpenAI 플랫폼 통합. Chat Completions / Responses API, function calling, structured output (JSON Schema), vision/audio multimodal, batch, embeddings, fine-tuning.
|
||||
|
||||
## 📖 구조화된 지식 (Synthesized Content)
|
||||
- **추출된 패턴:** "[[State|State]]less Interaction and Structured prompting" — 모델의 상태를 직접 관리하지 않고, 이전 대화 내용(History)을 포함한 프롬프트를 전송하여 문맥에 맞는 응답을 받아내는 비상태성 통신 패턴. 특히 최근에는 JSON 모드나 함수 호출(Function Calling)을 통해 결과를 정형 데이터로 받아 시스템 제어에 활용함.
|
||||
- **주요 엔드포인트:**
|
||||
- **Chat Completions (gpt-4o, gpt-3.5-turbo):** 텍스트 기반 대화 및 추론.
|
||||
- **Embeddings:** 텍스트를 벡터로 변환하여 검색 및 클러스터링에 활용.
|
||||
- **Audio (Whisper, TTS):** 음성 인식 및 합성.
|
||||
- **Images (DALL-E 3):** 이미지 생성 및 편집.
|
||||
- **의의:** 복잡한 인프라 구축 없이 누구나 고도화된 지능형 서비스를 즉각 배포할 수 있게 하여, 전 세계적인 AI 앱 서비스([[SaaS|SaaS]])의 폭발적 성장을 견인함.
|
||||
## 핵심
|
||||
|
||||
## ⚠️ 모순 및 업데이트 (Contradictions & Updates)
|
||||
- **과거 데이터와의 충돌:** 단순히 텍스트를 주고받던 단계를 넘어, 이제는 외부 도구를 호출하는 도구 사용(Tool Use) 능력과 파일 기반 지식 참조(Assistants API) 등 개발자의 역할을 코딩에서 '오케스트레이션'으로 전환시키고 있음.
|
||||
- **정책 변화:** Antigravity 프로젝트는 에이전트의 고도의 추론이 필요한 구간에서 OpenAI API를 최적화된 프롬프트 엔지니어링과 함께 사용하여, 로컬 모델이 해결하기 어려운 복잡한 논리 문제를 해결함.
|
||||
### 엔드포인트 (2025-2026)
|
||||
- **Responses API** (신규 권장): tools/state 통합, agentic 워크플로우.
|
||||
- **Chat Completions**: 레거시 호환, 광범위한 지원.
|
||||
- **Embeddings**: `text-embedding-3-small/large`.
|
||||
- **Audio**: `gpt-4o-audio-preview`, Whisper STT, TTS.
|
||||
- **Images**: `gpt-image-1` (생성/편집).
|
||||
- **Batch**: 50% 할인, 24h 내 처리.
|
||||
- **Realtime**: WebSocket 실시간 음성/텍스트.
|
||||
|
||||
## 🔗 지식 연결 (Graph)
|
||||
- GPT-Architecture-Foundations, [[Prompt-Engineering|Prompt-Engineering]]-Best-Practices, RAG-Foundations, [[Local-Brain-Management|Local-Brain-Management]]
|
||||
- **Raw Source:** 10_Wiki/Topics/AI/OpenAI-API-Integration.md
|
||||
### 모델 (대표)
|
||||
- **gpt-5 / gpt-5-mini / gpt-5-nano** (2025).
|
||||
- **gpt-4.1, gpt-4o, gpt-4o-mini** — 멀티모달.
|
||||
- **o3, o4-mini** — reasoning 모델.
|
||||
- **text-embedding-3-large** (3072 dim).
|
||||
|
||||
## 🤖 LLM 활용 힌트 (How to Use This Knowledge)
|
||||
### 핵심 기능
|
||||
- **Function calling / tools**: 구조화 함수 호출.
|
||||
- **Structured Outputs**: `response_format` + JSON Schema = 100% 스키마 준수.
|
||||
- **Vision**: 이미지 URL 또는 base64 입력.
|
||||
- **Audio in/out**: gpt-4o-audio (음성 입출력).
|
||||
- **Streaming**: SSE.
|
||||
- **Prompt caching**: 자동, 1024+ 토큰 prefix 50% 할인.
|
||||
- **Seed / temperature 0**: deterministic-ish.
|
||||
|
||||
**언제 이 지식을 쓰는가:**
|
||||
- *(TODO)*
|
||||
### 인증/보안
|
||||
- API key (`OPENAI_API_KEY`), Project keys (RBAC).
|
||||
- Rate limit: tier (Tier 1-5), TPM/RPM.
|
||||
- Org ID 헤더 분리.
|
||||
|
||||
**언제 쓰면 안 되는가:**
|
||||
- *(TODO)*
|
||||
## 💻 패턴
|
||||
|
||||
## 🧪 검증 상태 (Validation)
|
||||
|
||||
- **정보 상태:** needs_review
|
||||
- **출처 신뢰도:** A
|
||||
- **검토 이유:** *(P-Reinforce Phase 1 자동 정규화. 본문 검증 필요.)*
|
||||
|
||||
## 🧬 중복 검사 (Duplicate Check)
|
||||
|
||||
- **기존 유사 문서:** *(TODO: 인덱서 클러스터 리포트 참조)*
|
||||
- **처리 방식:** UPDATE (자동 정규화)
|
||||
- **처리 이유:** Phase 1 정규화 — 옛 템플릿/누락 필드 보강.
|
||||
|
||||
## 🕓 변경 이력 (Changelog)
|
||||
|
||||
| 날짜 | 변경 내용 | 처리 방식 | 신뢰도 |
|
||||
|------|-----------|-----------|--------|
|
||||
| 2026-05-08 | P-Reinforce Phase 1 정규화 (frontmatter + 헤더 표준화) | UPDATE | A |
|
||||
|
||||
## 💻 코드 패턴 (Code Patterns)
|
||||
|
||||
**패턴 1:** *(TODO: 이 프로젝트 컨벤션 반영한 구조 스켈레톤)*
|
||||
|
||||
```text
|
||||
# TODO
|
||||
### Python — 기본 chat
|
||||
```python
|
||||
from openai import OpenAI
|
||||
client = OpenAI()
|
||||
resp = client.chat.completions.create(
|
||||
model="gpt-4o-mini",
|
||||
messages=[{"role": "user", "content": "Hello!"}],
|
||||
temperature=0.7,
|
||||
)
|
||||
print(resp.choices[0].message.content)
|
||||
```
|
||||
|
||||
## 🤔 의사결정 기준 (Decision Criteria)
|
||||
### Structured Output (JSON Schema)
|
||||
```python
|
||||
from pydantic import BaseModel
|
||||
class Recipe(BaseModel):
|
||||
name: str
|
||||
ingredients: list[str]
|
||||
steps: list[str]
|
||||
|
||||
**선택 A를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
resp = client.beta.chat.completions.parse(
|
||||
model="gpt-4o-2024-08-06",
|
||||
messages=[{"role": "user", "content": "Pasta carbonara recipe"}],
|
||||
response_format=Recipe,
|
||||
)
|
||||
recipe: Recipe = resp.choices[0].message.parsed
|
||||
```
|
||||
|
||||
**선택 B를 써야 할 때:**
|
||||
- *(TODO)*
|
||||
### Function calling (tools)
|
||||
```python
|
||||
tools = [{
|
||||
"type": "function",
|
||||
"function": {
|
||||
"name": "get_weather",
|
||||
"description": "Get current weather",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"properties": {"city": {"type": "string"}},
|
||||
"required": ["city"],
|
||||
},
|
||||
},
|
||||
}]
|
||||
resp = client.chat.completions.create(
|
||||
model="gpt-4o", messages=[{"role":"user","content":"Weather in Seoul?"}],
|
||||
tools=tools, tool_choice="auto",
|
||||
)
|
||||
call = resp.choices[0].message.tool_calls[0]
|
||||
# dispatch → call.function.name with json.loads(call.function.arguments)
|
||||
```
|
||||
|
||||
**기본값:**
|
||||
> *(TODO)*
|
||||
### Vision (이미지 입력)
|
||||
```python
|
||||
resp = client.chat.completions.create(
|
||||
model="gpt-4o-mini",
|
||||
messages=[{"role": "user", "content": [
|
||||
{"type": "text", "text": "What's in this image?"},
|
||||
{"type": "image_url", "image_url": {"url": "https://.../cat.jpg"}},
|
||||
]}],
|
||||
)
|
||||
```
|
||||
|
||||
## ❌ 안티패턴 (Anti-Patterns)
|
||||
### Streaming (SSE)
|
||||
```python
|
||||
stream = client.chat.completions.create(
|
||||
model="gpt-4o-mini",
|
||||
messages=[{"role":"user","content":"Write a haiku"}],
|
||||
stream=True,
|
||||
)
|
||||
for chunk in stream:
|
||||
delta = chunk.choices[0].delta.content or ""
|
||||
print(delta, end="", flush=True)
|
||||
```
|
||||
|
||||
- **[안티패턴]:** *(TODO: 무엇을 하면 안 되는가 + 이유 + 대신 무엇을)*
|
||||
### Embeddings + cosine search
|
||||
```python
|
||||
import numpy as np
|
||||
def embed(text):
|
||||
return np.array(client.embeddings.create(
|
||||
model="text-embedding-3-small", input=text
|
||||
).data[0].embedding)
|
||||
|
||||
def cosine(a, b): return float(a @ b / (np.linalg.norm(a)*np.linalg.norm(b)))
|
||||
```
|
||||
|
||||
### Batch API (50% 할인)
|
||||
```python
|
||||
# 1) JSONL upload
|
||||
file = client.files.create(file=open("requests.jsonl","rb"), purpose="batch")
|
||||
# 2) batch
|
||||
batch = client.batches.create(
|
||||
input_file_id=file.id,
|
||||
endpoint="/v1/chat/completions",
|
||||
completion_window="24h",
|
||||
)
|
||||
# 3) poll status, download output_file_id when 'completed'
|
||||
```
|
||||
|
||||
### TypeScript — Responses API
|
||||
```ts
|
||||
import OpenAI from "openai";
|
||||
const client = new OpenAI();
|
||||
const resp = await client.responses.create({
|
||||
model: "gpt-4.1",
|
||||
input: "Summarize Anthropic's mission.",
|
||||
tools: [{ type: "web_search" }],
|
||||
});
|
||||
console.log(resp.output_text);
|
||||
```
|
||||
|
||||
### Retry + 비용 가드
|
||||
```python
|
||||
import time, openai
|
||||
def safe_call(fn, *a, **kw):
|
||||
for i in range(5):
|
||||
try: return fn(*a, **kw)
|
||||
except openai.RateLimitError: time.sleep(2**i)
|
||||
except openai.APIError as e:
|
||||
if e.status_code >= 500: time.sleep(2**i)
|
||||
else: raise
|
||||
```
|
||||
|
||||
## 결정 기준
|
||||
|
||||
| 목적 | 권장 모델/기능 |
|
||||
|---|---|
|
||||
| 일반 chat 저비용 | gpt-4o-mini |
|
||||
| reasoning 강함 | o4-mini / o3 |
|
||||
| 멀티모달 | gpt-4o |
|
||||
| 대량 비실시간 | Batch + gpt-4o-mini |
|
||||
| 임베딩 일반 | text-embedding-3-small |
|
||||
| 임베딩 고품질 | text-embedding-3-large |
|
||||
| 실시간 음성 | Realtime API + gpt-4o-realtime |
|
||||
| 스키마 보장 | Structured Outputs (response_format) |
|
||||
| 에이전트 | Responses API + tools |
|
||||
|
||||
기본값: **gpt-4o-mini + Structured Outputs + 캐싱**.
|
||||
|
||||
## 🔗 Graph
|
||||
|
||||
- 부모: [[LLM APIs]], [[Generative AI Platforms]]
|
||||
- 변형: [[Anthropic API]], [[Google Gemini API]], [[Azure OpenAI]]
|
||||
- 응용: [[RAG]], [[Function Calling]], [[Structured Output]], [[Voice Agents]]
|
||||
- Adjacent: [[Prompt Caching]], [[Embeddings]], [[Whisper]], [[Realtime API]]
|
||||
|
||||
## 🤖 LLM 활용
|
||||
|
||||
- 언제: chat/추출/요약/RAG 합성, function dispatcher, structured 추출, 임베딩 검색, 일괄 분류 (Batch).
|
||||
- 언제 X: PHI/PCI raw 데이터 (BAA/규정 확인), 하드 실시간 < 50ms (edge 모델), 결정론적 계산 (코드/계산기로).
|
||||
|
||||
## ❌ 안티패턴
|
||||
|
||||
- API key 클라이언트 번들에 노출 → 백엔드 프록시 필수.
|
||||
- 무한 retry (지수 백오프 없이) → rate limit 폭주.
|
||||
- temperature=0이면 deterministic이라 가정 (근사일 뿐).
|
||||
- 스키마 검증 없이 LLM JSON 신뢰 → Structured Outputs 또는 Pydantic 검증.
|
||||
- 매 호출마다 시스템 prompt 재구성 → prefix 캐싱 활용 (1024+ 토큰).
|
||||
- Batch에 실시간 요청 보내기 (24h 지연).
|
||||
|
||||
## 🧪 검증 / 중복
|
||||
|
||||
- 검증: golden eval set (precision/recall), 토큰 사용 모니터링, 회귀 테스트 모델 버전 lock.
|
||||
- 중복: [[Function Calling]] / [[Structured Output]] / [[Embeddings]] 각 기능 전용 페이지 ↔ 본 문서 통합 인덱스.
|
||||
|
||||
## 🕓 Changelog
|
||||
|
||||
- 2026-05-10: 표준 포맷, Responses API / gpt-5 / Structured Outputs / Batch 추가.
|
||||
|
||||
Reference in New Issue
Block a user