REODE: 멀티 LLM 프로바이더 SDK 호환성 점검

Date: 2026-03-18
Status: In Progress
Goal: GLM-5, MiniMax, DeepSeek을 REODE LLM 인프라에 통합하기 위한 호환성 조사

---

1. 프로바이더별 SDK 현황

프로바이더	SDK 패키지	버전	자체 SDK	OpenAI 호환
Anthropic (Claude)	anthropic	기존 사용	O	X (독자 API)
OpenAI	openai>=2.0.0	2.21.0 설치 / 2.28.0 최신	O	—
Zhipu (GLM-5)	zhipuai	2.1.5.20250825	O	O (base_url 스왑도 가능)
MiniMax	없음 (openai 권장)	—	X	O (base_url 스왑 공식 권장)
DeepSeek	없음 (openai 권장)	—	X	O (base_url 스왑)

---

2. REODE OpenAI Adapter 5개 메서드 호환성

REODE OpenAIAdapter가 사용하는 5개 메서드별 호환 여부:

메서드	SDK 기능	OpenAI	GLM-5	MiniMax	DeepSeek
generate()	chat.completions.create()	OK	OK	OK	OK
generate_structured()	수동 JSON 파싱	OK	OK	OK	OK
generate_parsed()	beta.chat.completions.parse() + Pydantic	OK	BROKEN	BROKEN	BROKEN
generate_stream()	stream=True	OK	OK	OK	OK
generate_with_tools()	tools + tool_choice	OK	OK	OK	OK (chat only)

generate_parsed() 실패 원인

beta.chat.completions.parse(response_format=PydanticModel)은 OpenAI의 json_schema 응답 형식에 의존.
GLM/MiniMax/DeepSeek 모두 json_schema 미지원 → generate_parsed() 호출 시 에러.

• GLM-5: json_object만 지원 (openai-agents issue #1595 확인)
• MiniMax: 문서 미확인 (미지원 추정)
• DeepSeek: beta 엔드포인트에서만 제한적 지원 (standard 미지원)

---

3. 프로바이더별 비호환 상세

GLM-5 (Zhipu)

항목	OpenAI	GLM-5	영향
json_schema response_format	O	X (json_object만)	generate_parsed() 실패
temperature 범위	(0, 2)	(0, 1)	값 클램핑 필요
max_completion_tokens	O	미확인 (max_tokens 사용)	파라미터명 분기
stream_options	O	미문서화	usage 추적 불가 가능
모델 ID	gpt-5.4 등	glm-5, glm-5-turbo	모델명 매핑 필요

MiniMax

항목	OpenAI	MiniMax	영향
json_schema response_format	O	미문서화	generate_parsed() 실패 추정
temperature 범위	(0, 2)	(0, 1]	값 클램핑 필요
presence_penalty	O	무시됨	사일런트 무시
frequency_penalty	O	무시됨	사일런트 무시
n 파라미터	1+	1만 지원	복수 응답 불가
이미지/오디오 입력	O	X	멀티모달 불가
function_call (deprecated)	O	X	tools 필수
모델 ID	gpt-5.4 등	MiniMax-M2.5 등	모델명 매핑 필요

DeepSeek

항목	OpenAI	DeepSeek	영향
json_schema response_format	O	beta 전용 (standard X)	generate_parsed() 실패
json_object mode	O	O (단, 프롬프트에 "json" 키워드 필수)	프롬프트 조작 필요
tool calling	O	deepseek-chat만 (deepseek-reasoner 불가)	모델별 분기
reasoning_content	X	O (reasoner 모델)	응답 파싱 분기
temperature (reasoner)	O	비활성	무시됨
stream_options	O	미문서화	usage 추적 불가 가능
parallel_tool_calls	O	미문서화	미지원 가능
모델 ID	gpt-5.4 등	deepseek-chat, deepseek-reasoner	모델명 매핑

---

4. 아키텍처 결정

결정: 혼합 전략

LLMClientPort (Protocol) — 5 methods
  ├── ClaudeAdapter          anthropic SDK (기존)
  ├── OpenAIAdapter          openai SDK (기존)
  │     ├── MiniMax          base_url 스왑 (자체 SDK 없음)
  │     └── DeepSeek         base_url 스왑 + reasoner 분기
  └── GlmAdapter             zhipuai SDK (자체 SDK 존재)

근거

• GLM: 자체 SDK(zhipuai)가 있고, OpenAI와 다른 고유 기능(assistant, video, character)이 있으므로 별도 Adapter
• MiniMax: 자체 SDK 없음, 공식적으로 OpenAI SDK 사용 권장 → OpenAI Adapter 확장
• DeepSeek: 자체 SDK 없음, OpenAI SDK 사용 권장 → OpenAI Adapter 확장 (reasoner 분기 추가)

변경 필요 파일

파일	변경	우선순위
openai_adapter.py	base_url/api_key 파라미터 + 인스턴스 클라이언트 + json_schema fallback	P1
config.py	zhipu/minimax/deepseek API key + base_url 설정	P1
token_tracker.py	MODEL_PRICING/CONTEXT_WINDOW 추가	P2
runtime.py	설정 기반 adapter 와이어링	P2
신규 glm_adapter.py	zhipuai SDK 기반 LLMClientPort 구현	P2

---

5. 핵심 해결 과제

과제 1: generate_parsed() fallback

3사 모두 json_schema 미지원 → fallback 전략 필요:

방안	설명	장점	단점
A: json_object + Pydantic 수동 파싱	response_format={"type": "json_object"} + model_validate_json()	범용, 간단	스키마 강제 불가
B: instructor 라이브러리	프로바이더별 structured output 자동 처리	프로바이더 추상화	외부 의존성
C: 프롬프트 기반 JSON 추출	JSON 블록을 프롬프트로 요청 + regex 추출	의존성 없음	불안정

과제 2: 파라미터 정규화

프로바이더별로 temperature 범위, 파라미터명, 지원 여부가 다름 → Adapter 레벨에서 정규화 필요.

과제 3: 모델 ID 매핑

통일된 모델 참조 체계 필요 (예: provider:model 형식 또는 config에서 매핑).

---

6. 모델 정보

GLM-5

모델	파라미터	Context	Input $/M	Output $/M
glm-5	744B MoE (44B active)	200K	$0.72	$2.30
glm-5-turbo	agent 최적화	200K	$1.20	$4.00

MiniMax

모델	Context	Input $/M	Output $/M
MiniMax-M2.5	205K	$0.30	$1.20
MiniMax-M2.5-Lightning	205K	$0.30	$2.40
MiniMax-M2.1	196K	$0.27	$0.95

DeepSeek

모델	Context	Input $/M	Output $/M	Tool Calling
deepseek-chat	128K	~$0.14	~$0.28	O
deepseek-reasoner	128K	~$0.55	~$2.19	X

---

7. OpenAI Agents SDK 참고

• 별도 패키지: pip install openai-agents (v0.12.3, 2026-03-16)
• openai>=2.x 위에서 동작하는 멀티 에이전트 오케스트레이션
• 비 OpenAI 프로바이더: LiteLLM 연동 필요
• 알려진 이슈: json_schema 강제 → GLM/MiniMax 깨짐 (issue #1595)
• REODE와의 관계: REODE는 자체 AgenticLoop + SubAgentManager를 가지므로 직접 사용하지 않음

---

---

8. Anthropic/OpenAI 대비 누락 기능 정밀 비교

REODE의 LLMClientPort 5개 메서드 + 인프라 기능을 Anthropic/OpenAI 기준으로 비교.

8.1 LLMClientPort 5개 메서드

메서드	Anthropic SDK	OpenAI SDK	zhipuai SDK	MiniMax (via openai)	DeepSeek (via openai)
generate()	messages.create()	chat.completions.create()	chat.completions.create()	chat.completions.create()	chat.completions.create()
generate_structured()	JSON 프롬프트 + 수동 파싱	JSON 프롬프트 + 수동 파싱	동일	동일	동일 (단, "json" 키워드 필수)
generate_parsed()	messages.parse()	beta.chat.completions.parse()	미지원 (json_schema X)	미지원 (json_schema X)	미지원 (standard X, beta 제한적)
generate_stream()	messages.stream()	stream=True	stream=True	stream=True	stream=True
generate_with_tools()	tool_use content block	tools + tool_calls	tools + tool_calls	tools + tool_calls	tools + tool_calls (chat only)

8.2 인프라 기능 비교

기능	Anthropic	OpenAI	GLM-5	MiniMax	DeepSeek
Retry + Backoff	REODE call_llm 내장	REODE OpenAIAdapter 내장	자체 구현 필요	openai SDK 재사용	openai SDK 재사용
Circuit Breaker	REODE CircuitBreaker	REODE CircuitBreaker	재사용 가능	재사용 가능	재사용 가능
Fallback Chain	config.FALLBACK_CHAIN	config.OPENAI_FALLBACK_CHAIN	별도 체인 필요	별도 체인 필요	별도 체인 필요
Token Tracking	response.usage 파싱	response.usage 파싱	response.usage 파싱 (동일 형태)	미확인 (usage 필드 여부)	response.usage 파싱
Usage Pricing	MODEL_PRICING dict	MODEL_PRICING dict	추가 필요	추가 필요	추가 필요
Context Window	MODEL_CONTEXT_WINDOW	MODEL_CONTEXT_WINDOW	추가 필요 (200K)	추가 필요 (205K)	추가 필요 (128K)
stream_options	N/A (다른 방식)	include_usage: True	미문서화	미문서화	미문서화
max_completion_tokens	max_tokens	max_completion_tokens	미확인 (max_tokens?)	미확인	OK

8.3 핵심 누락 사항 요약

공통 누락 (3사 모두)

#	누락	영향	대응 방안
N1	generate_parsed() (json_schema)	Pydantic 구조적 출력 불가	json_object + model_validate_json() fallback
N2	stream_options 미문서화	스트리밍 중 usage 추적 불가 가능	스트리밍 후 별도 usage 요청 또는 무시
N3	Fallback chain 미설정	모델 장애 시 자동 전환 불가	config에 프로바이더별 fallback chain 추가
N4	MODEL_PRICING/CONTEXT_WINDOW 미등록	토큰 비용 추적 + 컨텍스트 관리 불가	token_tracker.py에 모델 추가

GLM-5 고유 누락

#	누락	영향	대응 방안
G1	temperature 범위 (0,1) vs OpenAI (0,2)	temperature 1.0 이상 전달 시 에러	Adapter에서 min(temp, 0.99) 클램핑
G2	max_completion_tokens 미확인	파라미터 무시 가능	max_tokens로 전환 분기
G3	자체 SDK(zhipuai)의 tool_calls 응답 형태	OpenAI SDK와 미묘한 차이 가능	zhipuai SDK 직접 테스트 필요
G4	assistant/video 등 고유 API	REODE에서 사용 안 함	무시

MiniMax 고유 누락

#	누락	영향	대응 방안
M1	presence_penalty/frequency_penalty 무시됨	반복 제어 불가	문서화 + 경고
M2	n > 1 미지원	복수 응답 생성 불가	현재 REODE에서 미사용, 무시
M3	멀티모달 입력 미지원	이미지 분석 불가	현재 REODE에서 미사용, 무시
M4	usage 필드 반환 여부 미확인	토큰 추적 불가 가능	실제 호출 테스트 필요

DeepSeek 고유 누락

#	누락	영향	대응 방안
D1	deepseek-reasoner tool calling 미지원	reasoner 모델로 도구 사용 불가	deepseek-chat 강제 또는 모델 분기
D2	reasoning_content 필드	응답 파싱 시 추가 처리 필요	reasoner 응답에서 reasoning_content 분리
D3	reasoner에서 temp/top_p 비활성	파라미터 무시됨	모델별 파라미터 필터링
D4	json_object 모드에서 빈 content 반환 버그	JSON 파싱 실패 가능	retry + 빈 응답 체크

8.4 구현 우선순위

우선순위	작업	영향도	난이도
P1	N1: generate_parsed() fallback	3사 모두 깨짐	중
P1	N4: token_tracker 모델 등록	비용 추적	저
P2	N3: 프로바이더별 fallback chain	안정성	저
P2	G1: temperature 클램핑	GLM 에러 방지	저
P3	D1: reasoner 모델 분기	DeepSeek 한정	중
P3	N2: stream usage tracking	정확한 비용 추적	중

---

9. 추가 조사 필요 사항

#	항목	이유
R1	zhipuai SDK의 tool_calls 응답 형태 실제 테스트	OpenAI format과 미묘한 차이 가능
R2	MiniMax usage 필드 반환 여부 실제 테스트	문서에 없음
R3	GLM-5 max_tokens vs max_completion_tokens 실제 테스트	문서 불명확
R4	3사 모두 streaming tool_calls 지원 여부	실시간 도구 사용 시 중요
R5	GLM-5-turbo의 agent 최적화 구체적 차이	Zhipu 2026-03-16 출시, 상세 미공개
R6	instructor 라이브러리 호환성	프로바이더 추상화 대안

---

10. 추가 조사 결과

instructor 라이브러리 (핵심 발견)

instructor는 json_schema에 의존하지 않고 Mode.Tools (tool calling)로 structured output을 구현.
이 방식은 GLM/MiniMax/DeepSeek 모두 tool calling을 지원하므로 3사 모두 동작 가능.

항목	값
패키지	pip install instructor
지원 프로바이더	OpenAI, Anthropic, Google, DeepSeek, Mistral, Cohere + 15개
GLM/MiniMax 직접 지원	X — 공식 목록에 없음
임의 base_url	from_provider("deepseek/deepseek-chat", base_url="...") 형태로 가능
structured output 방식	Mode.Tools (기본) — tool calling으로 JSON 추출
reasoning 모델	Mode.MD_JSON — Markdown JSON 추출
스트리밍	create_partial(), create_iterable() 지원

핵심: generate_parsed() 문제의 해결 방안으로 instructor의 Mode.Tools 전략을 차용 가능.
tool calling은 3사 모두 지원하므로, json_schema 없이도 Pydantic 구조적 출력이 가능.

MiniMax 추가 확인

• Anthropic SDK도 지원 (OpenAI SDK뿐 아니라)
• tool calling: "trigger tool calls based on provided context" — 확인됨
• usage 필드: 문서에 명시 안 됨 — 실제 테스트 필요
• streaming: 지원 (SSE)

generate_parsed() 대안 전략 (수정)

기존 방안에 instructor 발견을 반영:

방안	설명	장점	단점	추천
A: json_object + Pydantic 수동 파싱	response_format=json_object + model_validate_json()	간단	GLM만 지원, MiniMax 미확인	△
B: instructor 라이브러리	Mode.Tools로 tool calling 기반 구조적 출력	3사 모두 동작, 검증됨	외부 의존성 추가	△
C: Tool-based structured output (자체 구현)	instructor의 Mode.Tools 패턴을 직접 구현	의존성 없음, 완전 제어	구현 필요	추천
D: 프롬프트 기반 JSON 추출	JSON 블록 요청 + regex 추출	의존성 없음	불안정	X

방안 C 구현 원리:

1. Pydantic 모델에서 JSON Schema 추출
2. 해당 스키마를 tool 정의로 변환 (가짜 tool)
3. generate_with_tools()로 호출 → LLM이 tool_call로 JSON 반환
4. tool_call arguments를 Pydantic으로 검증

이 패턴은 instructor가 내부적으로 하는 것과 동일하며, REODE의 generate_with_tools()가 3사 모두 동작하므로 확실함.

---

Sources

• zhipuai PyPI
• zhipuai-sdk-python-v4 GitHub
• Z.AI OpenAI Compatibility
• Z.AI Structured Output
• MiniMax OpenAI API Docs
• MiniMax Tool Calling Guide
• DeepSeek API Docs
• DeepSeek Function Calling
• OpenAI Agents SDK
• OpenAI Agents SDK json_schema issue #1595