DEV Community: Rihpig

클로드 2026년 무료 사용법: 가능한 모든 방법

Rihpig — Tue, 25 Aug 2026 08:08:55 +0000

2026년 무료 Claude 사용법: Sonnet 5, Claude Code, API까지

Claude는 2026년에도 무료로 사용할 수 있습니다. 평가판이나 만료되는 데모가 아니라, claude.ai는 Anthropic의 강력한 모델 중 하나인 Claude Sonnet 5를 영구 무료 요금제로 제공합니다. 핵심은 무료 경로별 제공 기능과 제한을 이해하는 것입니다. 일부 경로는 채팅 앱과 Claude Code를 제공하고, 일부는 단 한 푼도 쓰지 않고 Apidog로 테스트할 수 있는 API 액세스를 제공합니다.

지금 Apidog를 사용해 보세요

이 가이드에서는 공식 무료 요금제, 게스트 패스, 무료 API 크레딧, 다른 도구에 포함된 Claude 액세스까지 실제로 사용할 수 있는 무료 옵션을 정리합니다. 유료 요금제가 필요한지 판단하려면 Claude 무료 vs Pro 비교도 참고하세요.

Claude는 무료인가요?

네. claude.ai의 무료 요금제는 신용 카드가 필요하지 않고 만료되지 않습니다. 2026년 8월 기준으로 다음 기능을 제공합니다.

2026년 7월부터 무료 사용자의 기본 모델인 Claude Sonnet 5
더 빠르고 가벼운 응답을 위한 Claude Haiku 4.5
채팅 인터페이스의 웹 검색, 파일 업로드, 이미지 입력
웹, 데스크톱, 모바일 앱

다만 Claude Fable 5와 Opus급 모델은 포함되지 않습니다. Anthropic의 도움말 센터에 따르면 Fable 5는 Pro, Max, Team, Enterprise 요금제에서만 사용할 수 있습니다. 2026년 6월에 잠시 무료로 제공되었지만, Claude Fable 5를 무료로 사용하는 방법에서 소개한 프로모션은 2026년 7월 19일 종료되었습니다.

무료 사용량에도 제한이 있습니다. Anthropic은 정확한 수치를 공개하지 않지만, 커뮤니티 측정에 따르면 무료 요금제는 약 5시간의 롤링 창마다 15~40개의 메시지를 처리합니다. 수요가 급증하면 유료 사용자가 우선되므로 무료 용량이 줄어들 수 있습니다. 일상적인 질문과 짧은 코딩 세션에는 충분하지만, 길고 반복적인 작업에는 부족할 수 있습니다.

옵션 1: claude.ai 무료 요금제

가장 간단한 방법입니다.

claude.ai에 접속합니다.
이메일 또는 Google 계정으로 가입합니다.
Sonnet 5를 선택해 대화를 시작합니다.

무료 요금제의 Sonnet 5는 유료 사용자가 이용하는 것과 동일한 모델이며, 다운그레이드 버전이 아닙니다. 자세한 사용법은 Claude Sonnet 5를 무료로 사용하는 방법을 참고하세요. Sonnet 5는 코드 생성, 문서 분석, 다단계 추론을 처리하므로 많은 개발자는 품질보다 할당량에서 먼저 제한을 경험합니다. 모델 성능은 Claude Sonnet 5 벤치마크 분석에서 확인할 수 있습니다.

무료 할당량을 효율적으로 사용하는 방법

새 주제마다 새 채팅을 시작하세요. Claude는 매 턴 전체 스레드를 다시 읽기 때문에 긴 대화는 할당량을 더 빠르게 소모합니다.
빠른 검색에는 Haiku 4.5를 사용하세요. 채팅 작성기에서 모델을 바꿀 수 있으며, Haiku는 Sonnet보다 적은 용량을 사용합니다.
세션을 나누어 사용하세요. 5시간 롤링 창이 계속 갱신되므로, 한도에 도달하면 앱이 다음 사용 가능 시간을 알려줍니다.

옵션 2: Claude Code 게스트 패스

Claude Code를 사용하려면 게스트 패스가 가장 현실적인 무료 방법입니다. Anthropic은 Max 구독자에게 공유 가능한 패스를 제공하며, 각 패스는 신규 사용자에게 7일 동안 Pro 수준의 액세스와 Claude Code를 제공합니다.

Max 구독자에게 Claude Code에서 /passes를 실행해 달라고 요청하거나, 남는 패스를 공유하는 개발자 커뮤니티를 확인해 보세요.

주의할 점은 다음과 같습니다.

패스는 신규 계정에만 적용됩니다.
7일 동안 무료이지만 카드 등록이 필요하다는 보고가 있습니다.
패스 만료 후 자동으로 Pro 요금제가 청구되기보다는 무료 요금제로 돌아가지만, 추천 방식은 변경될 수 있으므로 사용 전에 약관을 확인하세요.

장기적인 사용 방법은 Claude Code를 무료로 사용하는 입증된 방법과 Anthropic 프로모션 기간에 프로모션 Claude Code 크레딧을 청구하는 방법에서 확인할 수 있습니다.

옵션 3: Apidog로 테스트하는 무료 API 크레딧

platform.claude.com의 신규 계정은 소액의 시작 크레딧을 받을 수 있습니다. 제3자 보고에 따르면 약 5달러이며, API를 통해 Sonnet 5나 Haiku 4.5를 실험하기에 충분한 규모입니다. 자세한 크레딧 확보 방법은 무료 Claude API 액세스에서 확인하세요.

5달러는 시행착오 요청만으로도 빠르게 소진될 수 있습니다. 이때 Apidog를 사용하면 API 비용을 줄이면서 안정적으로 개발할 수 있습니다.

Anthropic API 사양을 가져오세요. 엔드포인트, 헤더, 본문 스키마가 자동으로 채워지므로 curl을 수동으로 작성하거나 잘못된 요청으로 토큰을 낭비할 필요가 없습니다.
사용 사례별 정식 요청을 하나씩 테스트하세요. /v1/messages에 올바르게 구성된 호출을 보내고, 응답 구조를 확인한 뒤 예제로 저장합니다.
개발 중에는 Mock을 사용하세요. Apidog의 저장된 응답을 로컬 Mock 서버로 전환하면 실제 API 호출 없이 앱을 개발할 수 있습니다. 최종 검증 단계에서만 Claude API를 호출하세요.

이 방식은 개발 중 API 비용을 크게 줄이는 방법이며, Claude API 요금 절감 방법에서 권장하는 접근 방식이기도 합니다. 프로덕션 환경에서는 프롬프트 캐싱을 활용하면 유료 API 비용을 더 낮출 수 있습니다.

옵션 4: 이미 사용하는 도구에서 Claude 사용하기

다음 서비스도 무료 또는 제한된 무료 티어에서 Claude를 제공합니다.

GitHub Copilot: 선택 가능한 모델 중 Claude를 제공하므로, Copilot 구독이나 제한된 무료 티어를 통해 에디터에서 Claude를 사용할 수 있습니다.
Poe, DuckDuckGo AI Chat, Brave Leo: Claude 기반 모델을 무료 일일 한도와 함께 제공합니다.
Cursor, Windsurf: 평가판의 모델 옵션에 Claude가 포함되어 있습니다. 2주 평가 기간에 유용하며, Cursor에서 Claude Sonnet 5를 사용하는 방법에서 단계별 설정을 확인할 수 있습니다.

단, 이러한 통합 서비스가 항상 최신 또는 가장 큰 Claude 모델로 요청을 라우팅하는 것은 아닙니다. 시스템 프롬프트도 claude.ai와 다를 수 있으므로, 모델 동작이 중요한 작업에서는 실제 사용 모델을 확인하세요.

옵션 5: 클라우드 제공업체 평가판 크레딧

AWS Bedrock, Google Vertex AI, Azure AI Foundry는 Claude 모델을 제공하며, 신규 계정에 평가판 크레딧을 지급합니다. 스타트업이나 교육 크레딧이 이미 있다면 추가 비용 없이 Claude API를 사용할 수 있습니다.

클라우드별 설정은 다르지만, Bedrock, Vertex, Foundry에서 Claude Fable 5 실행하기의 연결 방식은 Sonnet 5에도 적용됩니다.

설정 난이도는 가장 높지만, 소비자용 무료 요금제에서는 Fable 5급 모델을 제공하지 않으므로 현재 Fable 5급 모델을 무료로 사용할 수 있는 주요 경로입니다.

무료 Claude의 제한 사항

무료 사용의 한계를 미리 알면 불필요한 시행착오를 줄일 수 있습니다.

Fable 5를 사용할 수 없습니다. 유료 요금제에서만 제공되며, Pro에서는 정액 구독과 별도로 사용량 기반 크레딧에서 차감됩니다. 전체 요금제 비교는 Claude Fable 5에 액세스하는 방법을 참고하세요.
피크 시간대 우선순위가 낮습니다. 서버가 혼잡하면 무료 용량이 줄어듭니다.
세션 제한이 더 엄격합니다. 장시간 에이전트 실행이나 대규모 프로젝트는 제한에 도달하기 쉽습니다. Claude Fable 5 속도 제한 설명에서 Anthropic의 제한 시스템을 확인할 수 있습니다.

매주 제한에 도달한다면 월 20달러의 Pro 요금제가 비용 대비 가치가 있는지 검토할 시점입니다. 그전까지는 위의 무료 옵션으로 대부분의 개인 사용을 처리할 수 있습니다.

자주 묻는 질문

2026년 무료 Claude 요금제는 어떤 모델을 사용하나요?

기본 모델은 Claude Sonnet 5이며, 빠른 응답이 필요할 때 Haiku 4.5를 사용할 수 있습니다. API로 전환할 계획이라면 Sonnet 5 전체 가이드를 참고하세요.

무료 사용자는 몇 개의 메시지를 받을 수 있나요?

Anthropic은 고정된 수치를 공개하지 않습니다. 커뮤니티 추정으로는 서버 부하와 메시지 길이에 따라 5시간 롤링 창당 약 15~40개의 메시지를 보낼 수 있습니다.

Claude API를 무료로 사용할 수 있나요?

platform.claude.com의 신규 계정은 소액의 시작 크레딧을 받을 수 있습니다. Bedrock, Vertex, Foundry의 클라우드 평가판 크레딧도 사용할 수 있습니다. 개발 트래픽은 Apidog의 Mock 서버로 처리하고, 중요한 호출에만 실제 크레딧을 사용하세요.

Claude Code는 무료인가요?

무료 요금제에는 포함되지 않습니다. 게스트 패스로 7일 동안 사용할 수 있으며, 프로모션 크레딧은 1년에 몇 차례 제공될 수 있습니다. API 시작 크레딧으로도 짧은 세션을 일부 실행할 수 있습니다.

무료로 시작하고, 똑똑하게 테스트하세요

claude.ai의 무료 요금제는 2026년에 최신 모델을 비용 없이 사용하기 위한 가장 쉬운 방법입니다. 실제 Sonnet 5를 카드 등록이나 만료일 없이 사용할 수 있습니다.

Claude Code를 체험하려면 게스트 패스를 사용하고, API 통합을 개발하려면 시작 크레딧을 활용하세요. 개발 과정에서는 Apidog를 API와 코드 사이에 배치해 Mock이 테스트 트래픽을 처리하도록 구성하면 됩니다. 이렇게 하면 무료 크레딧은 실제 검증이 필요한 호출에만 사용할 수 있습니다.

Apidog를 무료로 다운로드한 뒤 Claude 계정과 연결하고, 실제 사용량이 필요해질 때만 유료 요금제로 업그레이드하세요.

그록 2026년 무료 사용법: 가능한 모든 방법

Rihpig — Tue, 25 Aug 2026 07:58:14 +0000

Grok은 무료인가요? 2026년 무료 사용·API 크레딧 가이드

Grok이 주목받고 있습니다. xAI는 2026년 8월 12일 Grok 4.6을 출시했고, 이 모델은 인공지능 분석 지수에서 GPT-5.6과 동등한 수준에 도달하면서도 대부분의 경쟁 제품보다 API 가격이 저렴합니다. 벤치마크와 50만 토큰 컨텍스트 창은 Grok 4.6 분석에서 확인할 수 있습니다.

지금 Apidog를 사용해 보세요

결론부터 말하면 Grok은 무료로 사용할 수 있습니다. 다만 무료 채팅, 유료 모델, API 크레딧은 서로 다른 조건을 가집니다. 이 글에서는 2026년 기준 무료 사용 경로와 API 크레딧을 효율적으로 테스트하는 방법을 정리합니다.

Grok은 무료인가요?

네. grok.com과 X 앱에서 계정을 만들면 신용카드나 구독 없이 Grok과 채팅할 수 있습니다.

무료 티어로 할 수 있는 작업은 다음과 같습니다.

질문과 답변
텍스트 초안 작성
링크 요약
기본 웹·X 검색

다만 다음 제한을 알아야 합니다.

Grok 4.6 플래그십 모델은 무료가 아닙니다.
이미지·비디오 생성은 유료 플랜 전용입니다.
API는 프로모션 크레딧을 모두 사용하면 사용량 기반으로 과금됩니다.
더 높은 한도와 최신 모델은 SuperGrok 등 유료 티어에서 제공합니다.

grok.com과 X 앱에서 무료로 채팅하기

가장 간단한 방법은 grok.com입니다. 이메일, Google 계정 또는 X 계정으로 가입한 뒤 바로 사용할 수 있습니다. 이미 X 앱을 사용한다면 Grok 탭에서도 같은 무료 액세스를 이용할 수 있습니다.

무료 사용량 제한

xAI는 현재 무료 계정의 고정 메시지 한도를 공개하지 않습니다. 예전 가이드에서 보이는 “2시간마다 10개 프롬프트”는 2026년 중반에 폐기된 정보입니다.

현재 무료 한도는 수요에 따라 유동적입니다.

피크 시간에는 소프트 제한에 빨리 도달할 수 있습니다.
한가한 시간에는 더 많은 요청을 처리할 수 있습니다.
익명 또는 로그아웃 상태에서는 더 엄격한 제한이 적용될 수 있습니다.

무료 한도를 오래 사용하려면 다음처럼 요청하세요.

짧은 질문 여러 개를 하나의 구조화된 프롬프트로 합칩니다.
긴 세션이 필요하면 X 앱보다 웹 앱을 우선 사용합니다.
반드시 로그인한 상태로 사용합니다.

무료 사용자는 어떤 모델을 쓰나요?

무료 사용자는 Grok 4.6이 아닌 구형 또는 경량 모델을 사용합니다. xAI는 인터페이스에서 정확한 모델명을 명확히 표시하지 않습니다.

서드파티 보고서는 Grok 4.3급 또는 Grok 4 Mini 계열일 가능성을 언급하지만, 확정된 정보는 아닙니다. 공통적으로 알려진 점은 다음과 같습니다.

일반 대화, 초안 작성, 기본 검색에는 충분합니다.
확장 추론, DeepSearch, 장문 컨텍스트 처리에는 제한이 있습니다.
여러 출처를 비교하는 리서치, 대형 문서 분석, 저장소 전체 코드 작업에는 적합하지 않을 수 있습니다.

이런 고난도 작업이 바로 Grok 4.6, GPT-5.6, Claude Fable 5 비교에서 다루는 Grok 4.6의 핵심 영역입니다.

이전에 Grok 4.5를 무료로 사용하는 방법을 따랐다면, 패턴은 동일합니다. 새 플래그십은 우선 유료로 출시되고, 다음 세대가 나오면 이전 세대가 무료 티어에 제공될 수 있습니다.

xAI는 무료 API 크레딧을 제공하나요?

개발자에게 중요한 부분입니다. 여러 크레딧 추적 사이트는 다음 혜택을 보고합니다.

신규 API 계정에 약 25달러의 가입 크레딧
모델 학습용 API 트래픽 공유에 동의한 팀에 월별 약 150달러 상당의 선택적 크레딧

하지만 x은 다음과 같습니다.

항목	가격
입력 토큰	20만 토큰 미만 프롬프트 기준, 100만 토큰당 2달러
출력 토큰	100만 토큰당 6달러
컨텍스트 창	50만 토큰

기본 입력 요율 기준으로 25달러는 약 1,200만 입력 토큰을 처리할 수 있습니다. API 키, 엔드포인트, 첫 요청은 Grok 4.6 API 시작하기에서 확인하세요.

API 비용에서 주의할 점

토큰 비용 외에 도구 호출 비용이 추가될 수 있습니다.

웹 검색
X 검색
코드 실행

에이전트가 모든 요청에서 검색을 반복하면 프로모션 크레딧이 빠르게 소진될 수 있습니다. 필요한 요청에만 도구를 활성화하고, 응답을 재사용할 수 있는 구조로 테스트하는 것이 좋습니다.

Grok Imagine과 Voice는 무료인가요?

Grok Imagine

이미지·비디오 생성기인 Grok Imagine은 무료가 아닙니다. xAI는 2026년 초까지 무료 액세스를 단계적으로 축소했고, 봄까지 무료 티어를 완전히 제거한 것으로 보고됩니다.

2026년 8월 기준 가격은 다음과 같습니다.

이미지: 장당 0.04달러
비디오: 초당 0.08달러

합법적이고 비용 효율적인 사용 방법은 예산에 맞춰 Grok Imagine API 사용하기를 참고하세요. 또한 “제한 없음” 주장에 대한 설명도 확인할 수 있습니다.

Grok Voice

음성 모드는 상대적으로 접근성이 좋습니다. 모바일 앱에서 제한된 형태로 무료 사용자에게 제공된 사례가 있지만, xAI는 현재 명확한 사용량 제한을 공개하지 않았습니다.

사용하려면 다음을 시도하세요.

iOS 또는 Android용 Grok 앱을 설치합니다.
채팅 화면에서 파형 아이콘을 찾습니다.
무료 사용자는 유료 사용자보다 짧은 세션을 예상합니다.

자세한 설정은 Grok 음성 무료 사용 가이드를 참고하세요.

무료 Grok으로 할 수 없는 것

2026년 무료 계정에서는 일반적으로 다음 기능을 사용할 수 없습니다.

Grok 4.6 또는 4.5: 플래그십 모델은 SuperGrok 및 API 전용입니다.
이미지·비디오 생성: Grok Imagine은 유료 전용입니다.
DeepSearch 및 확장 추론: 연구 수준 기능은 구독자용입니다.
예측 가능한 요청 한도: 서버 부하에 따라 무료 용량이 달라집니다.
피크 시간 우선순위: 서버가 혼잡하면 무료 트래픽의 우선순위가 낮습니다.

가벼운 텍스트 기반 작업에는 무료 티어로도 충분할 수 있습니다. 하지만 Grok 기반 애플리케이션을 개발한다면 무료 채팅보다 API 크레딧을 사용하는 편이 낫습니다.

Apidog로 API 크레딧을 오래 사용하는 방법

API 개발 중에는 같은 엔드포인트를 반복 호출하면서 크레딧이 낭비되기 쉽습니다. 파싱, 재시도, 오류 처리, UI 연결을 테스트하려고 같은 요청을 50번 보내면 실제 토큰 비용도 50번 발생합니다.

Apidog를 사용하면 이를 줄일 수 있습니다.

xAI API를 Apidog 프로젝트로 가져옵니다.
grok-4.6에 실제 요청을 한 번 보냅니다.
받은 응답을 저장합니다.
Apidog의 모의 서버에서 현실적인 Grok 응답을 재생합니다.
새 모델 출력이 필요할 때만 기본 URL을 api.x.ai로 되돌립니다.

이 방식으로 다음을 테스트할 수 있습니다.

응답 파싱
재시도 로직
오류 처리
UI 상태 처리
팀 공유 컬렉션
API 키 환경 변수
응답 구조 검증용 스크립트 어설션

스트리밍 응답과 오류 케이스까지 포함한 절차는 Grok 4.6 API 테스트 및 디버깅에서 확인할 수 있습니다.

모의 응답으로 개발 호출을 절반만 줄여도, 25달러 크레딧을 며칠이 아니라 몇 주 동안 사용할 수 있습니다.

자주 묻는 질문

X 프리미엄 없이도 Grok은 무료인가요?

네. 2026년 기준 무료 Grok은 X 프리미엄 구독이 아니라 grok.com 또는 X 계정에 연결됩니다. 프리미엄과 SuperGrok 구독자는 더 높은 한도와 최신 모델을 받지만, 일반 무료 계정으로도 채팅할 수 있습니다.

Grok API는 무료인가요?

아니요. API는 사용량 기반으로 과금됩니다. 다만 신규 계정에 프로모션 크레딧이 제공될 수 있으므로 xAI 콘솔에서 확인하세요. Grok 4.3 API 무료 크레딧 가이드의 이전 프로모션은 변경되었을 수 있습니다.

현재 무료 Grok 모델은 무엇인가요?

xAI는 정확한 모델명을 공개하지 않습니다. 무료 사용자는 Grok 4.6이 아닌 구형 경량 모델을 사용하며, 보고서에서는 Grok 4.3 또는 Grok 4 Mini 계열로 추정합니다.

Grok에서 이미지를 무료로 만들 수 있나요?

아니요. Grok Imagine의 무료 티어는 2026년에 종료되었습니다. 가장 저렴한 방법은 유료 구독 또는 장당 0.04달러의 API 사용입니다.

요약

2026년에도 무료 Grok은 사용할 수 있지만 제한적입니다. 무료 티어에서는 구형 모델로 채팅할 수 있고, 이미지 생성은 사용할 수 없으며, API 크레딧은 현재 프로모션에 따라 달라집니다.

일상적인 질문에는 grok.com을 사용하세요. API 개발 시에는 xAI 콘솔의 크레딧을 확인하고, 반복 테스트에는 모의 응답을 사용하세요. Apidog 다운로드를 통해 실제 모델 호출은 꼭 필요한 시점에만 수행하면 무료 크레딧을 더 오래 유지할 수 있습니다.

노트북LM 2026년 활용법: 구글의 무료 연구 도구 실용 가이드

Rihpig — Tue, 25 Aug 2026 07:36:58 +0000

NotebookLM 사용법: 무료 기능, 소스 제한, 개발자 API 문서 활용법

NotebookLM은 PDF, 문서, 링크, 동영상 등을 업로드해 질문 가능한 지식 베이스로 바꿔줍니다. 업로드한 소스만 근거로 답변하며 클릭 가능한 인용도 제공합니다. 2026년에는 소스에서 팟캐스트 스타일 오디오, 내레이션 비디오 설명자, 마인드 맵까지 생성할 수 있습니다. NotebookLM의 에이전트 모드가 궁금하다면 심층 연구 분석도 참고하세요.

오늘 Apidog를 사용해 보세요

이 글에서는 NotebookLM의 설정 방법, 소스 제한, 유용한 기능, 유료 등급의 차이를 정리합니다. 개발자를 위해 API 문서를 분석하고 검증하는 워크플로우도 함께 살펴봅니다. NotebookLM은 API 문서를 이해하는 데 강하고, API 사양을 설계·테스트하는 Apidog와도 잘 맞습니다.

아래 내용은 2026년 8월 기준이며, Google 공식 지원 문서를 바탕으로 정리했습니다.

NotebookLM이란? 무료인가요?

NotebookLM은 Google의 소스 기반 AI 연구 비서입니다. 표준 등급은 무료이며 다음 한도를 제공합니다.

노트북 100개
노트북당 소스 50개
일일 채팅 쿼리 50개
일일 오디오 개요 3개
일일 비디오 개요 3개
보고서, 플래시카드, 퀴즈, 마인드 맵 일일 생성 10개

Google 계정과 브라우저가 필요하며, Android 앱 또는 iOS 모바일 앱에서도 사용할 수 있습니다.

NotebookLM의 핵심은 “소스 기반”이라는 점입니다. 일반 챗봇은 학습 데이터와 공개 웹을 바탕으로 답변하므로 질문에서 벗어나거나 사실을 만들어낼 수 있습니다. 반면 NotebookLM은 업로드한 소스만 사용하고, 주장마다 인라인 인용을 표시합니다. 소스에 답이 없으면 추측하지 않고 해당 정보가 없다고 알려줍니다.

NotebookLM과 Gemini Notebook

Google은 2026년부터 NotebookLM을 Gemini 브랜드에 통합하고 있습니다. 공식 지원 페이지에서는 이제 Gemini Notebook이라는 이름을 사용하지만, 제품과 제한은 동일합니다. 앱은 여전히 notebooklm.google.com에서 이용할 수 있으며, 이 글에서는 익숙한 이름인 NotebookLM을 사용하겠습니다.

첫 노트북 설정하기

기본 설정은 약 2분이면 끝납니다.

notebooklm.google.com에 접속해 Google 계정으로 로그인합니다. 대기 목록이나 신용카드는 필요하지 않습니다.
새 노트북 만들기를 클릭합니다. 노트북은 하나의 연구 주제, 강의, API 또는 거래를 담는 프로젝트 컨테이너입니다. 관련 없는 주제를 섞지 말고 목적을 하나로 좁히세요.
첫 번째 소스를 추가합니다. PDF, Google 문서·슬라이드, 웹사이트 URL, YouTube 링크, 오디오, Markdown, 붙여넣은 텍스트를 사용할 수 있습니다. 처음에는 문서 3~4개를 추가하는 것이 좋습니다.
색인이 끝날 때까지 기다립니다. 소스 크기에 따라 수초에서 수분이 걸리며, 이후 노트북의 자동 요약이 생성됩니다.
채팅 패널에서 구체적인 질문을 합니다. 답변의 인용 번호를 클릭하면 소스의 정확한 구절로 이동할 수 있습니다.
유용한 답변은 스튜디오 패널에 고정해 메모로 저장합니다.

핵심 사용 루프는 간단합니다.

소스 추가 → 질문 → 인용 확인 → 유용한 답변 저장

다른 기능도 모두 이 흐름을 확장한 것입니다.

소스 종류와 제한 사항

답변 품질은 소스 품질에 크게 좌우됩니다.

추가할 수 있는 소스

PDF 및 텍스트 파일(스캔 문서 포함)
Google Drive에서 가져온 Google 문서와 Google 슬라이드
NotebookLM이 텍스트로 스크랩할 수 있는 공개 웹사이트 URL
캡션이 있는 YouTube 동영상
강의 녹음이나 회의 녹음 같은 오디오 파일
Markdown 파일과 복사한 텍스트 블록

YouTube 동영상은 화면의 픽셀을 분석하는 것이 아니라 캡션 또는 스크립트를 읽습니다.

무료 플랜의 소스 한도

무료 플랜은 노트북당 50개의 소스를 지원합니다. 개별 소스는 오랫동안 파일당 약 500,000단어 또는 200MB까지 지원해 왔습니다. 따라서 900페이지 PDF도 추가할 수 있고, 이러한 PDF를 한 노트북에 최대 50개까지 넣을 수 있습니다. 대부분의 프로젝트에는 충분한 용량입니다.

알아두어야 할 문제

로그인이나 유료 구독이 필요한 웹사이트는 스크랩되지 않습니다. 필요한 페이지를 먼저 PDF로 저장하세요.
캡션이 없는 YouTube 동영상은 읽을 텍스트가 없어 제대로 분석되지 않습니다.
소스는 자동으로 최신 상태가 되지 않습니다.
원본 Google 문서가 변경되면 해당 소스의 동기화 버튼을 눌러 업데이트해야 합니다.

시간을 투자할 가치가 있는 기능

오디오 개요

오디오 개요는 NotebookLM의 대표 기능입니다. 두 명의 AI 호스트가 소스를 팟캐스트 형식으로 토론하며, 매우 자연스러운 음성을 제공합니다.

대화형 모드를 사용하면 에피소드 중간에 질문할 수 있습니다. 생성 전에 특정 장에 집중하거나 배경 자료를 제외하도록 지시할 수도 있습니다. 무료 사용자는 하루에 3개를 생성할 수 있습니다.

비디오 개요

비디오 개요는 소스에서 내레이션이 포함된 슬라이드 스타일 설명 영상을 만듭니다. 시각적 스타일을 선택할 수 있으며 오디오 개요보다 생성 속도는 느립니다.

원본 자료를 읽지 않을 사람에게 내용을 공유해야 할 때 유용합니다. 무료 플랜에서는 하루 3개로 제한됩니다.

마인드 맵

마인드 맵은 모든 소스의 핵심 개념을 가지 형태의 다이어그램으로 정리합니다.

처음 접하는 주제를 빠르게 파악하려면 다음 방식으로 사용하세요.

마인드 맵을 생성합니다.
이해하기 어려운 가지를 찾습니다.
해당 가지를 클릭해 관련 내용을 확인합니다.
필요한 부분을 다시 질문합니다.

보고서, 플래시카드, 퀴즈

스튜디오 패널에서는 소스를 다음과 같은 형식으로 변환할 수 있습니다.

브리핑 문서
학습 가이드
플래시카드
자가 테스트 퀴즈

학생에게는 학습 자료로 유용하고, 업무에서는 새로 맡은 주제를 회의 전에 파악하는 브리핑 문서로 활용하기 좋습니다. 이 기능들은 무료 플랜에서 하루 10회 생성 한도를 공유합니다.

내부적으로 모든 등급은 2026년 Gemini 3 모델을 사용합니다. 유료 구독은 더 지능적인 모델을 제공하는 것이 아니라 더 높은 용량과 사용 한도를 제공합니다.

무료 플랜과 유료 플랜 비교

Google은 NotebookLM 상위 등급을 독립적인 NotebookLM 플랜이 아니라 Google AI 구독으로 판매합니다.

제한	무료	Google AI Plus	Google AI Pro	Google AI Ultra
노트북	100	200	500	500
노트북당 소스	50	100	300	500~600
일일 채팅 쿼리	50	200	500	2,500~5,000
일일 오디오/비디오 개요	3	6	20	비디오 최대 200개

Pro는 대부분의 지역에서 생성된 비디오의 워터마크를 제거합니다. Ultra는 Google의 Veo 비디오 모델을 기반으로 한 시네마틱 비디오 개요 스타일을 제공합니다.

Google AI Pro는 월 19.99달러이며, Plus는 4.99달러로 알려져 있습니다. 여러 국가의 학생은 Google AI Pro를 1년 동안 무료로 사용할 수 있어, 높은 한도를 가장 저렴하고 합법적으로 이용하는 방법이 될 수 있습니다.

업그레이드할 시점

제한에 도달할 때까지 무료 플랜을 사용하세요. 많은 헤비 유저가 가장 먼저 부딪히는 한도는 일일 채팅 쿼리 50개입니다. 이 한도가 부족해졌을 때 Plus 또는 Pro를 검토하면 됩니다.

개발자 워크플로우: API 문서 분석하기

API 문서는 NotebookLM이 잘 처리하는 자료입니다. 길고 구조화되어 있으며, 필요한 세부 정보가 여러 문서에 흩어져 있기 때문입니다.

다음과 같이 설정해 보세요.

통합하려는 API 전용 노트북을 만듭니다.
제공업체의 참조 문서를 URL 또는 PDF로 추가합니다.
관련 RFC를 추가합니다. 예를 들어 OAuth 2.0에는 RFC 6749가 적합합니다.
직접 작성한 OpenAPI 사양을 Markdown 또는 공유 문서로 내보내 추가합니다.
실제 개발 질문을 입력합니다.

예를 들면 다음과 같습니다.

배치 엔드포인트의 속도 제한은 무엇인가요?
토큰 새로고침 흐름에는 어떤 범위가 필요한가요?
우리 사양의 어떤 엔드포인트가 Retry-After 헤더 없이 429를 반환하나요?

NotebookLM은 사양의 정확한 섹션을 인용해 답변합니다. 문서 사이트를 여러 탭으로 오가며 검색하는 것보다 효율적입니다. Gemini API를 사용하는 팀이라면 Google의 참조 문서를 추가하고 모델 매개변수에 대해 질문할 수도 있습니다.

NotebookLM의 한계

NotebookLM은 문서를 읽지만 실제 엔드포인트를 호출하지는 않습니다. 서버가 이미 두 릴리스 전에 변경되었더라도, 오래된 응답 스키마를 정확하게 인용할 수 있습니다.

사양은 약속이고, 프로덕션 환경에서는 그 약속을 검증해야 합니다. 이때 Apidog를 함께 사용하면 다음 작업을 수행할 수 있습니다.

OpenAPI 사양을 단일 진실 공급원으로 관리
실제 API 요청 실행
스키마에 따른 응답 검증
문서 판독기로는 찾기 어려운 변경 감지

권장 워크플로우는 다음과 같습니다.

NotebookLM으로 API 문서 이해 → Apidog로 실제 동작 검증 → 변경된 검증 사양을 NotebookLM에 다시 내보내기

자주 묻는 질문

NotebookLM이 업로드한 데이터로 학습하나요?

Google은 무료 및 유료 개인 계정에서 사용자의 소스, 쿼리 또는 응답을 모델 훈련에 사용하지 않는다고 명시합니다. Workspace 계정에는 추가적인 계약상 데이터 보호도 적용됩니다.

다만 정책은 변경될 수 있으므로 민감한 자료를 업로드할 때는 일반적인 보안 주의를 유지하세요.

다른 사람과 노트북을 공유할 수 있나요?

가능합니다. Drive 파일처럼 뷰어와 편집자 권한으로 노트북을 공유할 수 있습니다. 뷰어는 소스를 변경하지 않고도 노트북과 채팅할 수 있습니다.

오디오 개요에는 공개 공유 링크도 제공할 수 있으며, 이를 통해 AI 팟캐스트 에피소드를 다른 사람에게 공유할 수 있습니다.

사용할 수 있는 NotebookLM API가 있나요?

2026년 8월 기준으로 공개 NotebookLM API는 없습니다.

프로그래밍 방식으로 소스 기반 답변을 구현하려면 Gemini 모델을 직접 사용해 애플리케이션을 구축하는 방법이 현실적입니다. Ollama를 통한 Gemini 3 Pro 같은 자체 호스팅 옵션은 로컬 실행을 담당하고, Google File API는 클라우드 업로드를 처리할 수 있습니다.

어떤 언어를 지원하나요?

채팅과 출력은 수십 가지 언어를 지원합니다. 소스의 언어와 관계없이 출력 언어를 설정할 수 있습니다.

오디오 개요도 다양한 언어를 지원하지만, 비영어권 음성은 영어 호스트보다 완성도가 낮을 수 있습니다.

마무리

NotebookLM은 무료 플랜만으로도 상당히 많은 기능을 제공합니다.

노트북당 소스 50개
인용이 포함된 답변
오디오 및 비디오 생성
마인드 맵
보고서, 플래시카드, 퀴즈

이번 주에 실제 문제 하나를 정해 전용 노트북을 만들어 보세요. 기본 사용법을 익혔다면 세 가지 실제 시나리오도 다음 읽을거리로 적합합니다.

로드할 자료가 API 문서라면 마지막 단계로 검증을 추가하세요. NotebookLM은 문서가 무엇을 말하는지 알려줍니다. Apidog를 다운로드해 사양을 설계하고, 모의 테스트와 실제 테스트를 실행해 문서가 계속 정확한지 확인하세요.

DeepSeek 무료? 챗, API 요금과 2026년 모든 무료 이용법

Rihpig — Tue, 25 Aug 2026 07:16:00 +0000

짧은 답부터 말하면, DeepSeek의 채팅 앱은 무료입니다. API는 유료지만 저렴하고, 모델 가중치는 공개되어 있어 DeepSeek에 비용을 지불하지 않고 직접 실행할 수도 있습니다. 어떤 사용 방식을 선택하느냐에 따라 답이 달라지므로, 자세한 내용은 DeepSeek V4 사용 방법에서 확인할 수 있습니다.

오늘 Apidog를 사용해 보세요

이 글에서는 비용에 집중합니다. 2026년 8월 기준 DeepSeek 가격 페이지의 실제 수치를 바탕으로 무료인 항목과 유료인 항목, 각 선택지의 비용을 정리합니다. API를 사용한다면 Apidog로 DeepSeek 엔드포인트를 테스트하고 모의해 실제 호출 횟수를 줄일 수 있습니다.

DeepSeek은 무료인가요?

사용하는 표면에 따라 다릅니다.

채팅(웹 및 모바일 앱): 무료 구독료나 Plus 요금제가 없습니다. 가입 후 바로 사용할 수 있습니다.
API: 유료지만 저렴함 비피크 시간 기준 저가형 모델의 출력 토큰은 100만 개당 $0.66입니다. 신규 계정에는 무료 크레딧이 없으므로 첫 호출 전에 잔액을 충전해야 합니다.
모델 가중치: 무료 다운로드 및 실행 V4 제품군은 Hugging Face에서 MIT 라이선스로 제공됩니다. 비용은 하드웨어와 전기료뿐입니다.

정리하면 채팅은 무료이고, API는 저렴하며, 자체 호스팅은 하드웨어가 있다면 사실상 무료입니다.

무료 채팅 앱과 제한 사항

chat.deepseek.com의 DeepSeek 어시스턴트와 iOS/Android 앱은 무료입니다. 추론 모드, 파일 업로드, 웹 검색도 포함됩니다. ChatGPT나 Claude와 달리 유료 소비자 요금제로 업그레이드할 필요 없이 무료 요금제만 제공됩니다.

다만 제한은 비용이 아니라 운영 측면에 있습니다.

공식 일일 메시지 할당량이 공개되어 있지 않음
트래픽이 많을 때 서버 혼잡 응답이 발생할 수 있음
생성 속도가 느려질 수 있음
API 접근, 팀 작업 공간, 가동 시간 보장이 없음

개인 연구, 초안 작성, 코딩 질문에는 무료 앱만으로도 충분합니다.

또한 소비자 앱은 중국에서 호스팅되며, 프롬프트는 DeepSeek의 개인정보 보호 정책에 따라 DeepSeek 서버에서 처리됩니다. 민감한 데이터를 다룬다면 로컬 실행을 고려하십시오.

DeepSeek API 가격

API는 무료가 아닙니다. 2026년 8월 16일 기준 DeepSeek은 피크 시간과 비피크 시간에 따라 요금을 다르게 부과합니다.

피크 시간: 평일 01:00~04:00 UTC, 06:00~10:00 UTC
비피크 시간: 그 외 시간
비피크 요금은 피크 요금의 절반

요금은 토큰 100만 개 기준입니다.

모델	캐시 히트 입력	캐시 미스 입력	출력
`deepseek-v4-flash`	$0.007 / $0.014	$0.22 / $0.44	$0.66 / $1.32
`deepseek-v4-pro`	$0.022 / $0.044	$0.66 / $1.32	$1.98 / $3.96
`deepseek-v4-flash-vision-exp`	$0.007 / $0.014	$0.22 / $0.44	$0.66 / $1.32

각 셀은 비피크 / 피크 순서입니다.

비용을 줄이는 세 가지 방법

컨텍스트 캐싱 활용 반복되는 프롬프트 접두사, 고정 시스템 프롬프트, 예시 메시지는 자동으로 캐시됩니다. 캐시 히트 요금은 Flash의 캐시 미스 요금보다 약 31배 저렴합니다.
비피크 시간에 배치 작업 실행 코드를 변경하지 않고도 API 비용을 절반으로 줄일 수 있습니다.
모델별 비용 비교 피크 시간에도 V4 Flash 출력은 100만 토큰당 $1.32입니다. 비슷한 GPT급 플래그십 모델보다 몇 배 저렴할 수 있습니다.

예를 들어 비피크 시간에 Flash 모델로 매월 입력 토큰 1,000만 개(대부분 캐시됨)와 출력 토큰 200만 개를 처리하면 약 $1.50가 듭니다. 무료는 아니지만 취미 프로젝트에는 부담이 적은 수준입니다.

V4 Pro가 추가 비용을 정당화하는 경우는 V4 Pro-0813 API 가이드에서 확인할 수 있습니다.

무료 또는 거의 무료인 API 경로

DeepSeek 자체 플랫폼은 신규 계정에 시험용 크레딧을 제공하지 않습니다. 무료 또는 저비용으로 시작하려면 다음 방법을 사용할 수 있습니다.

OpenRouter 무료 모델 풀 OpenRouter는 신용카드 없이 20개 이상의 모델을 $0에 제공합니다. 다만 2026년 중반 기준 DeepSeek 무료 변형 모델은 풀에서 제외되었습니다. 현재 OpenRouter의 DeepSeek 목록은 유료이며, V4 Flash는 입력 토큰 100만 개당 약 $0.035부터 시작합니다. 다른 모델에서는 매일 50회의 무료 요청을 제공하므로, 비용을 지불하기 전에 프로토타입을 만들 수 있습니다.
클라우드 플랫폼 가입 크레딧 클라우드 제공업체나 추론 호스트의 가입 크레딧을 호스팅된 DeepSeek 모델에 사용할 수 있습니다. 모델 자체는 유료지만 크레딧이 소진될 때까지 무료로 이용할 수 있습니다.
DeepSeek 플랫폼에 최소 금액 충전 요금이 낮기 때문에 $2 잔액만으로도 오랫동안 사용할 수 있습니다. 완전 무료는 아니지만 실제 DeepSeek API를 사용하는 가장 간단한 방법입니다.

현재 무료 변형 모델을 제공하는 플랫폼은 DeepSeek 무료 API 키를 얻는 방법에서 정기적으로 업데이트됩니다.

DeepSeek을 로컬에서 무료로 실행하기

DeepSeek은 상업적 사용, 미세 조정, 재배포를 허용하는 MIT 라이선스로 Hugging Face에 모델 가중치를 공개합니다.

2026년 8월 기준 V4 제품군은 다음과 같습니다.

V4 Flash: 총 284B 매개변수, 활성 매개변수 13B
V4 Pro: 약 1.7T 매개변수의 전체 가중치가 프리뷰로 공개됨

문제는 하드웨어입니다.

V4 Flash: 심하게 양자화하면 약 33GB VRAM, FP8에서는 단일 80GB H100 필요
V4 Pro: 전체 가중치가 약 900GB에 달해 데이터센터급 환경 필요

일반 데스크톱에서는 더 작은 증류 모델이나 이전 세대 모델이 현실적입니다. Ollama로 DeepSeek R1을 로컬에서 실행하는 방법을 참고하면 소비자용 하드웨어에서도 약 10분 만에 API 키 없이 추론 모델을 실행할 수 있습니다.

로컬 실행의 장점은 다음과 같습니다.

토큰당 요금 없음
속도 제한 없음
데이터가 기기를 떠나지 않음
오프라인 사용 가능

반대로 양자화, vLLM 또는 SGLang 같은 서비스 스택, GPU 비용을 직접 관리해야 합니다. 사용량이 적다면 GPU 비용이 API 비용보다 비쌀 수도 있습니다.

채팅, API, 로컬 중 무엇을 선택할까?

질문, 초안 작성, 모델 평가: 채팅 앱 비용은 $0이고 설정이 필요하지 않습니다.
제품 또는 자동화 구축: API 취미 프로젝트라면 월 수 센트에서 수 달러 수준입니다. OpenAI 호환 API이므로 대부분의 SDK에서 기본 URL만 변경하면 됩니다.
데이터 프라이버시, 오프라인 사용, 기존 GPU 활용: 로컬 가중치 사용료는 없지만 하드웨어 비용과 운영 부담이 가장 큽니다.

대부분의 개발자는 결국 API를 사용하게 됩니다. 이때 매번 테스트할 때마다 실제 토큰을 소비하지 않는 방법이 중요합니다.

실제 호출은 한 번만, 나머지는 Apidog로 모의하기

DeepSeek API는 OpenAI 형식을 따르므로 Apidog에서 빠르게 가져올 수 있습니다.

OpenAI 호환 사양을 추가합니다.
기본 URL을 https://api.deepseek.com으로 설정합니다.
API 키를 환경 변수에 저장합니다.
요청을 전송합니다.
응답, 처리 시간, 스트리밍 토큰을 확인합니다.

비용 절감은 Apidog의 모의 기능에서 시작됩니다. 실제 DeepSeek 응답을 한 번 캡처한 뒤, 이후 프론트엔드와 통합 테스트에서는 실제와 동일한 응답을 모의 서버로 재현할 수 있습니다.

그러면 다음 작업을 모두 $0에 수행할 수 있습니다.

CI 테스트
UI 상태 검증
오류 처리 테스트
프론트엔드 통합 테스트

실제 API는 모델 동작을 검증해야 하는 몇 번의 호출에만 사용합니다. 특히 피크 시간에는 요금이 두 배가 되므로, 이 방식만으로도 청구서를 크게 줄일 수 있습니다.

자주 묻는 질문

DeepSeek 채팅은 무제한인가요?

DeepSeek은 채팅 앱의 메시지 제한을 공개하지 않습니다. 실제 사용량은 고정된 할당량보다 서버 용량의 영향을 받습니다. 트래픽이 많으면 “서버 혼잡” 응답이 발생할 수 있습니다. 문제가 계속되면 DeepSeek V4를 무료로 사용하는 방법을 참고하십시오.

DeepSeek API는 무료 체험을 제공하나요?

아니요. 신규 플랫폼 계정은 잔액이 0인 상태로 시작하며 프로모션 크레딧이 없습니다. 첫 요청 전에 충전해야 합니다. 대안으로 애그리게이터 플랫폼이나 클라우드 가입 크레딧을 사용할 수 있습니다.

DeepSeek은 오픈 소스인가요?

가중치는 MIT 라이선스로 공개되어 있어 대부분의 사용자는 이를 오픈 소스로 봅니다. 다만 학습 데이터와 전체 학습 파이프라인은 공개되지 않았기 때문에, 일부는 “오픈 소스” 대신 “오픈 웨이트”라고 부릅니다. 자체 호스팅은 무료이며 상업적으로 사용할 수 있습니다.

비용을 지불하지 않고 DeepSeek을 코딩에 사용할 수 있나요?

네. 무료 채팅 앱으로 일회성 코딩 질문을 처리하거나, 회사의 에이전트 CLI인 DeepSeek Harness를 API 비용 없이 로컬 모델에서 실행할 수 있습니다. 설정 방법은 DeepSeek Harness란 무엇인가를 참고하십시오.

결론

DeepSeek은 채팅을 통한 평가에는 무료이고, API를 통한 구축에는 매우 저렴하며, 하드웨어를 직접 제공하면 자체 호스팅도 무료입니다.

가장 실용적인 접근 방식은 다음과 같습니다.

채팅 앱으로 품질을 평가합니다.
제품을 만들 때 API로 전환합니다.
테스트 응답은 Apidog로 모의합니다.
실제 API 호출은 모델 동작을 검증할 때만 사용합니다.

Apidog를 다운로드해 DeepSeek API를 가져오고, 실제 호출 하나를 확인한 뒤 나머지 테스트는 무료 모의 서버로 실행해 보세요.

DeepSeek V4-Flash-Vision API 사용법 (이미지 입력 가이드)

Rihpig — Mon, 24 Aug 2026 10:49:56 +0000

DeepSeek V4-Flash Vision Exp API 사용법: 이미지 입력, 비용, 제한 사항

DeepSeek의 가장 저렴한 모델이 이제 이미지를 처리할 수 있습니다. 2026년 8월 21일, DeepSeek은 텍스트 전용 모델과 동일한 가격으로 이미지를 입력받고, 동일한 프로덕션 API를 사용하는 비전 지원 모델 deepseek-v4-flash-vision-exp를 출시했습니다. 이미지는 이미지당 최대 384개의 입력 토큰으로 요금이 계산됩니다. 공식 출시 노트에 따르면 이 모델은 V4-Flash의 텍스트 기능에 이미지 이해 기능을 더했으며, DeepSeek은 멀티모달 에이전트 성능이 Opus 4.8에 가깝다고 설명합니다.

지금 Apidog를 사용해 보세요

이 가이드에서는 deepseek-v4-flash-vision-exp의 특징, 모델 ID의 Exp가 프로덕션 사용에 의미하는 것, 이미지를 전송하는 세 가지 방법, 주요 제한 사항, 멀티모달 요청을 테스트하는 방법을 설명합니다. 비전 요청은 텍스트와 이미지가 섞이고 페이로드가 빠르게 커지므로, 터미널에서 JSON을 직접 편집하기보다 Apidog에서 요청을 관리하는 편이 효율적입니다.

`deepseek-v4-flash-vision-exp`란 무엇인가

이 모델은 이미지 인코더가 추가된 V4-Flash-0731입니다. DeepSeek에 따르면 에이전트 워크로드, 추론, 세계 지식 등 텍스트 작업에서는 기본 V4-Flash와 일치합니다. 따라서 기존 V4-Flash 요청에 이미지 입력이 필요하다면 동일한 텍스트 기능을 유지하면서 비전 모델로 전환할 수 있습니다.

OpenRouter 모델 목록은 이 모델을 총 284B개 매개변수 중 13B개가 활성화되는 희소 MoE(Mixture-of-Experts) 모델로 설명합니다.

V4-Flash는 DeepSeek의 보급형 모델 라인입니다. 텍스트 모델이 출시됐을 때의 내용은 DeepSeek V4-Flash API 가이드에서 확인할 수 있습니다.

비전 기능도 플래시 가격이 적용되므로, 멀티모달 API 중에서도 비용이 낮은 편입니다. 다만 “멀티모달 에이전트 벤치마크에서 Opus 4.8에 가깝다”는 내용은 공급업체의 주장입니다. 실제 워크로드를 이전하기 전에 자체 문서와 평가 데이터로 성능을 검증해야 합니다.

Exp라는 라벨이 붙어 있지만 샌드박스 전용 모델은 아닙니다. 다른 V4 모델과 동일한 속도 제한 및 SLA(서비스 수준 계약)를 사용하는 프로덕션 API 엔드포인트에서 실행되며, 대기 목록이나 별도의 접근 요청도 필요하지 않습니다.

가격: 텍스트 모델과 동일한 플래시 요율

DeepSeek의 가격 페이지에 따르면 deepseek-v4-flash-vision-exp의 가격은 텍스트 전용 deepseek-v4-flash와 동일합니다.

구분	비피크 시간	피크 시간
입력, 캐시 히트(100만 토큰당)	$0.007	$0.014
입력, 캐시 미스(100만 토큰당)	$0.22	$0.44
출력(100만 토큰당)	$0.66	$1.32

이미지는 이미지당 최대 384개의 입력 토큰으로 토큰화되어 입력 요율로 청구됩니다. 피크 시간의 캐시 미스 요율을 적용하면 이미지 한 장의 최대 비용은 다음과 같습니다.

384 / 1,000,000 × $0.44 = 약 $0.00017

따라서 이미지 1,000장의 입력 비용은 커피 한 잔보다 낮을 수 있습니다. 단, 실제 비용에는 텍스트 입력과 모델 출력 토큰도 포함됩니다.

텍스트 모델의 두 가지 가격 정책도 그대로 적용됩니다.

비피크 시간 요율은 피크 시간의 절반입니다.
피크 시간은 평일 UTC 01:00~04:00 및 06:00~10:00입니다.
반복되는 입력에는 컨텍스트 캐싱이 적용됩니다.
V4 라인의 컨텍스트 창은 가격 페이지에 1M 토큰으로 명시되어 있지만, 실제 출력 길이는 이보다 훨씬 짧게 제한됩니다.

반복적인 시스템 프롬프트를 여러 이미지에 함께 보내는 워크로드라면 캐시 히트 요율을 활용할 수 있습니다.

이미지를 전송하는 세 가지 방법

모델은 DeepSeek의 표준 Chat Completions 엔드포인트를 사용합니다.

https://api.deepseek.com/chat/completions

메시지의 content 배열에 텍스트와 이미지 블록을 함께 넣어 요청합니다. V4-Flash Responses API 출시 안내에 설명된 것처럼 메시지 스타일 및 응답 스타일 호출도 지원됩니다.

1. Base64 인라인 이미지

이미지를 읽어 데이터 URL로 인코딩하는 방식입니다. 별도의 파일 호스팅이 필요 없고 요청 하나만으로 테스트할 수 있지만, 이미지당 32MiB 제한이 있습니다.

import base64
from openai import OpenAI

client = OpenAI(
    [REDACTED CREDENTIAL]
    base_url="https://api.deepseek.com",
)

with open("invoice.png", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

response = client.chat.completions.create(
    model="deepseek-v4-flash-vision-exp",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Extract the line items and totals as JSON.",
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": f"data:image/png;base64,{b64}"
                    },
                },
            ],
        }
    ],
)

print(response.choices[0].message.content)

2. 외부 URL

이미지를 Base64로 인코딩하지 않고 공개적으로 접근 가능한 URL을 전달합니다. URL 길이는 최대 8,192자입니다.

{
  "type": "image_url",
  "image_url": {
    "url": "https://example.com/chart.png"
  }
}

이미지가 이미 CDN이나 공개 스토리지에 있다면 이 방법이 가장 간단합니다.

3. Files API의 `file_id` 참조

이미지를 먼저 업로드한 뒤 반환된 파일 ID를 요청에서 재사용합니다. DeepSeek Files API는 이미지 업로드를 무료로 허용하며, 이미지당 64MiB까지 지원합니다.

{
  "type": "file",
  "file": {
    "file_id": "file-api-xxxxxxxxxxxxxxxx"
  }
}

다음 기준으로 전송 방식을 선택하면 됩니다.

일회성 호출: Base64 인라인
이미지가 공개 CDN에 있음: 외부 URL
같은 이미지를 여러 요청에서 재사용: Files API의 file_id

`detail` 매개변수 설정

각 이미지에는 선택적 detail 필드를 지정할 수 있습니다.

"low": 이미지를 512×512로 축소합니다. 가장 저렴하고 빠르며 분류 수준의 질문에 적합합니다.
"high" 또는 "original": 원본 치수를 유지합니다. 밀집된 문서나 작은 텍스트를 읽을 때 유리합니다.
"auto": API가 적절한 수준을 선택합니다.

내부적으로 이미지는 토큰 계산을 위해 대략 800×800 크기로 정규화되며, 이미지당 384토큰 상한이 적용됩니다.

영수증, 문서, 대시보드처럼 OCR 정확도가 중요한 작업이라면 실제 데이터셋으로 "low"와 "high"를 비교하세요. 이 모델의 이미지 입력 비용 차이는 작지만, 해상도에 따른 인식 정확도 차이는 클 수 있습니다.

프로덕션 전에 확인할 제한 사항

제한 사항	값
요청당 최대 이미지 수	600
인라인(Base64) 이미지 크기	32 MiB
Files API 이미지 크기	64 MiB
총 요청 본문 크기	48 MiB
이미지 치수	각 면당 8,192px
이미지 15개 이상 포함 시 이미지 치수	각 면당 4,096px
외부 URL 길이	8,192자
이미지가 허용되는 메시지	`user` 메시지만 가능

마지막 제한은 특히 중요합니다. system 또는 assistant 메시지에 이미지를 넣으면 400 오류가 발생합니다.

여러 이미지를 하나의 요청에 포함할 수 있으며, 텍스트와 이미지도 자유롭게 섞을 수 있습니다. 따라서 다음과 같은 에이전트 루프를 구성할 수 있습니다.

화면이나 문서 이미지를 캡처합니다.
모델에 이미지와 질문을 함께 보냅니다.
모델의 추론 결과를 확인합니다.
툴 호출이나 다음 작업을 실행합니다.

DeepSeek은 같은 날 DeepSeek Harness 0.1.1에 이 모델의 기본 지원을 추가했습니다. 해당 스택은 DeepSeek Harness 개요에서 확인할 수 있습니다.

또한 텍스트 모델과 동일하게 툴 호출도 비전 기능과 함께 사용할 수 있습니다. 자세한 흐름은 함수 호출 가이드를 참고하세요.

`Exp`가 프로덕션 코드에 의미하는 것

Exp는 결제나 접근 권한에 대한 제한이 아니라, 모델이 예고 없이 수정되거나 교체될 수 있음을 나타내는 라벨입니다.

다음과 같이 운영 환경을 구성하면 변경 영향을 줄일 수 있습니다.

모델 ID를 한 곳에서 관리하기

애플리케이션 코드 여러 곳에 모델 ID를 직접 입력하지 말고 환경 변수나 설정 파일에서 관리합니다.

DEEPSEEK_VISION_MODEL=deepseek-v4-flash-vision-exp

코드에서는 설정값을 참조합니다.

import os

model = os.environ["DEEPSEEK_VISION_MODEL"]

텍스트 전용 대체 모델 유지하기

이미지가 없는 요청은 안정적인 deepseek-v4-flash로 라우팅할 수 있습니다. DeepSeek에 따르면 비전 모델은 텍스트 작업에서 기본 텍스트 모델과 일치하므로, 이미지 입력이 필요한 트래픽만 비전 모델로 분리하는 보수적인 구성이 가능합니다.

평가 결과를 스냅샷으로 저장하기

실험 모델이 수정되거나 비실험적 후속 모델이 출시되면 동일한 데이터셋으로 이전·이후 결과를 비교해야 합니다. 공급업체 벤치마크보다 자체 문서, 영수증, 스크린샷, 차트 등 실제 입력에 대한 평가 결과를 기준으로 판단하세요.

예제: 문서 파이프라인 비용 계산

월간 스캔 청구서 50,000장을 처리한다고 가정해 보겠습니다.

청구서당 이미지 1개
청구서당 지시 프롬프트 200토큰
호출당 JSON 출력 약 400토큰

이미지 입력 비용

50,000 × 384 = 19.2M 토큰
19.2M × $0.44 = $8.45

텍스트 입력 비용

50,000 × 200 = 10M 토큰
10M × $0.44 = 약 $4.40

반복되는 지시 블록에 컨텍스트 캐싱이 적용되면 대부분의 입력이 캐시 히트 요율로 계산됩니다.

10M × $0.014 = 약 $0.14

출력 비용

50,000 × 400 = 20M 토큰
20M × $1.32 = $26.40

피크 시간 요율을 기준으로 계산한 총비용은 한 달에 약 $35~$40입니다. 배치 작업을 평일 UTC 01:00~10:00의 피크 시간 외에 실행하면 비용은 대략 절반으로 줄어듭니다.

이 계산에서 출력 토큰이 비용의 대부분을 차지한다는 점에 주목하세요. 이미지 입력이 저렴한 경우에는 이미지를 더 작게 만드는 것보다 응답 형식을 제한하는 편이 효과적일 수 있습니다. 산문 설명 대신 필요한 필드만 포함한 간결한 JSON을 요청하면 이미지 전처리보다 더 큰 비용 절감 효과를 얻을 수 있습니다.

이러한 비용 구조는 에이전트 루프에도 영향을 줍니다. 최고급 멀티모달 모델에서는 비용 때문에 반복 실행하기 어려웠던 “스크린샷 → 추론 → 행동” 사이클을 프레임당 384토큰 수준으로 운영할 수 있습니다.

Apidog에서 멀티모달 요청 테스트하기

비전 요청은 터미널에서 수동으로 반복하기 어렵습니다. Base64 문자열은 요청 본문을 읽기 힘들게 만들고, detail 설정을 비교할 때마다 거의 동일한 페이로드를 다시 편집해야 합니다.

다음 순서로 테스트 환경을 구성하세요.

1. 요청 템플릿을 한 번 저장하기

Apidog 프로젝트에 요청을 저장하고 모델과 detail 값을 변수로 분리합니다.

{{model_id}}
{{detail}}

테스트 이미지나 detail 수준을 바꿀 때 요청 본문 전체를 수정하지 않고 변수만 변경할 수 있습니다.

2. 이미지 인코딩 자동화하기

사전 요청 스크립트에서 이미지 파일을 읽고 Base64 문자열을 주입합니다. 그러면 화면에 표시되는 요청 본문은 읽기 쉬운 상태로 유지하면서 실제 전송 시에는 데이터 URL을 사용할 수 있습니다.

3. 구조화된 응답을 검증하기

모델에 JSON 출력을 요청했다면 응답을 파싱하고 필수 필드를 어설션으로 검사하세요.

예를 들어 청구서 파이프라인이라면 다음 항목을 검증할 수 있습니다.

항목 배열이 존재하는가
총액 필드가 숫자 형식인가
각 항목에 설명과 금액이 있는가

이렇게 하면 “응답이 괜찮아 보인다”는 주관적인 판단을, 실험 모델이 변경될 때마다 다시 실행할 수 있는 통과·실패 테스트로 바꿀 수 있습니다.

4. 프런트엔드 응답을 모의하기

프롬프트를 조정하는 동안에는 실제 API 호출 없이 프런트엔드 개발을 진행할 수 있도록 응답 형태를 모의하세요. Apidog의 스마트 목업을 사용하면 정의한 스키마에 맞는 응답을 제공할 수 있습니다.

Apidog 무료 다운로드를 통해 설정을 완료한 뒤, DeepSeek이 실험 모델을 수정할 때 동일한 요청과 어설션을 다시 실행할 수 있습니다.

자주 묻는 질문

`deepseek-v4-flash-vision-exp`는 무료인가요?

무료는 아니지만 비용이 매우 낮습니다. 텍스트 모델의 플래시 요율과 동일하게 청구되며, 이미지는 이미지당 최대 384개의 입력 토큰으로 계산됩니다. DeepSeek Files API의 이미지 저장소는 무료이고, 이미지가 요청에 포함될 때만 사용량이 발생합니다.

`deepseek-v4-flash`를 대체하나요?

아닙니다. 텍스트 모델은 안정적인 ID로 유지됩니다. 비전 모델은 텍스트 작업에서 텍스트 모델과 일치한다고 설명되지만, Exp 모델의 변경 가능성을 감수해야 합니다. 보수적인 구성은 이미지 트래픽만 deepseek-v4-flash-vision-exp로 라우팅하는 것입니다.

Anthropic 스타일 API 형식으로 사용할 수 있나요?

가능합니다. DeepSeek의 V4 엔드포인트는 Chat Completions, Messages, Responses 형식의 호출을 모두 허용합니다. 따라서 기존 클라이언트의 호출 스타일을 유지하면서 이미지 블록을 추가할 수 있습니다.

전체 제품군에서 공유되는 엔드포인트 메커니즘은 V4 Pro API 상세 가이드에서 확인할 수 있습니다.

GPT 또는 Claude 비전 모델과 가격을 비교하면 어떤가요?

이미지당 384토큰으로 계산되며, 입력 비용은 100만 토큰당 $0.22~$0.44입니다. 따라서 최고급 멀티모달 모델보다 한 자릿수 낮은 가격대일 수 있습니다. 다만 실제 선택 기준은 가격만이 아니라 자신의 워크로드에서의 정확도입니다. 앞서 설명한 평가 시나리오로 직접 비교해야 합니다.

요약

deepseek-v4-flash-vision-exp는 V4-Flash의 텍스트 기능에 이미지 입력을 추가한 실험적 비전 모델입니다. 텍스트 모델과 동일한 플래시 가격이 적용되고, 이미지당 최대 384개의 입력 토큰으로 계산되며, Base64·외부 URL·Files API 참조라는 세 가지 입력 경로를 제공합니다.

프로덕션에 적용할 때는 다음을 지키세요.

모델 ID를 설정값으로 분리합니다.
이미지가 허용되는 user 메시지에만 이미지 블록을 넣습니다.
detail 수준을 실제 데이터로 평가합니다.
응답을 구조화된 JSON으로 제한하고 필드를 어설션합니다.
실험 모델의 변경에 대비해 평가 결과를 스냅샷으로 저장합니다.

Apidog에서 요청 템플릿과 어설션을 한 번 구성해 두면, 지금 Exp 모델을 테스트할 수 있을 뿐 아니라 후속 모델이 출시된 날에도 동일한 기준으로 다시 평가할 수 있습니다.

DeepSeek Harness에서 모든 모델 실행 방법

Rihpig — Thu, 20 Aug 2026 07:59:46 +0000

DeepSeek Harness(dsh)는 DeepSeek 자체 모델을 내장하지만 특정 모델에 묶이지 않습니다. 제공자를 구성으로 정의하고 OpenAI 호환 엔드포인트와 자격 증명을 연결하면, 로컬 Ollama·사내 게이트웨이·DashScope 호환 모드의 Qwen·Anthropic·OpenAI 등 URL 뒤에 있는 모델을 같은 방식으로 에이전트 세션에서 실행할 수 있습니다.

지금 Apidog 사용해 보기

이 글에서는 제공자 설정 블록의 키를 설명하고, 다음 세 가지 구성 레시피를 제공합니다.

Ollama 로컬 모델
호스팅된 OpenAI 호환 엔드포인트(DashScope의 Qwen)
내장 카탈로그 제공자

인용한 구성 내용은 2026년 8월 20일에 확인한 마스터 브랜치의 공식 제공자 가이드를 기준으로 합니다. dsh는 개발자 프리뷰이며, 호환성을 깨뜨리는 변경이 발생할 수 있습니다. 프로덕션에 적용하기 전에 현재 설치한 버전의 문서와 릴리스 노트를 확인하십시오.

DeepSeek Harness가 처음이라면 먼저 DeepSeek Harness의 개념과 동작 방식을 확인한 뒤 이 글의 제공자 설정을 적용하십시오.

에이전트 하네스에서 모델을 교체하는 이유

에이전트 하네스는 다음 루프를 반복합니다.

모델이 계획을 세웁니다.
도구를 호출합니다.
도구 결과를 읽습니다.
다음 작업을 결정합니다.

하네스는 이 루프를 관리하고, 모델은 교체 가능한 구성 요소입니다. 모델을 교체하는 주요 이유는 세 가지입니다.

비용 관리

에이전트 세션은 도구 결과가 계속 컨텍스트에 추가되므로 토큰 사용량이 빠르게 늘어납니다. 일반 작업은 더 저렴한 모델로 보내고, 복잡한 작업만 더 강력한 모델로 보내면 워크플로를 바꾸지 않고 비용을 조절할 수 있습니다.

예를 들어 일상적인 세션에는 DeepSeek V4-Flash를 사용하고, 고난도 작업에만 V4-Pro를 기본값으로 선택할 수 있습니다.

데이터 지역성

코드베이스나 도구 출력이 외부 네트워크로 나가면 안 되는 환경에서는 자체 인프라의 모델을 가리키면 됩니다. 로컬 런타임 또는 사내 게이트웨이를 baseURL로 설정하면 프롬프트, 파일 내용, 도구 출력이 외부 제공자로 전송되지 않습니다.

로컬 개발과 반복 테스트

플러그인을 개발하거나 에이전트 동작을 검증할 때는 매번 API 크레딧을 소모하거나 네트워크에 의존하지 않는 편이 좋습니다. 작은 로컬 모델로 도구 호출 루프와 플러그인 연결을 먼저 확인한 다음, 실제 작업에서는 더 강력한 모델로 전환할 수 있습니다.

이 구조는 dsh의 플러그인 아키텍처에서 나옵니다. 모델 어댑터도 교체 가능한 플러그인이며, 제공자 경로는 dsh-llm-pi-ai 플러그인이 관리합니다. 자세한 경로 정의는 플러그인 구성 카탈로그에서 확인할 수 있습니다.

사용자 입장에서 필요한 작업은 하나의 YAML 제공자 블록을 추가하는 것입니다.

제공자 블록: 키별 설명

사용자 지정 제공자는 $DSH_HOME/settings.yaml에 추가합니다. 웹 UI에서는 Settings → Models에서 생성할 수 있습니다.

공식 문서의 기본 예시는 다음과 같습니다.

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: legacy-chat
        - id: vision-preview
          input: [text, image]

`my-gateway`

제공자 ID입니다.

설정에서 이 제공자를 식별하는 영구 이름입니다.
나중에 변경하면 기존 설정이나 참조를 추적하기 어려울 수 있으므로 의미 있는 이름을 사용하십시오.
예: ollama-local, qwen-dashscope, company-gateway

`apiKeyEnv`

API 키가 들어 있는 환경 변수의 이름입니다.

apiKeyEnv: GATEWAY_API_KEY

실제 키를 YAML에 직접 넣지 마십시오. dsh는 이 이름을 사용해 실행 환경에서 값을 읽습니다.

export GATEWAY_API_KEY="your-secret-key"

`api`

엔드포인트와 통신할 프로토콜입니다.

api: openai-completions

OpenAI 호환 API를 노출하는 로컬 런타임, 게이트웨이, 호스팅 제공자에는 openai-completions를 사용합니다.

`baseURL`

dsh가 요청을 보낼 API 루트입니다.

baseURL: https://gateway.example/v1

대부분의 OpenAI 호환 엔드포인트는 /v1까지 포함해야 합니다. DashScope처럼 별도 호환 경로를 사용하는 경우에는 제공자의 문서에 있는 전체 경로를 사용하십시오.

`models`

이 제공자를 통해 선택할 수 있는 모델 목록입니다.

models:
  - id: legacy-chat
  - id: vision-preview

id는 서버가 요청 본문에서 기대하는 모델 ID와 정확히 일치해야 합니다.

`input`

모델이 처리할 수 있는 입력 모달리티입니다. 사용자 지정 모델은 기본적으로 텍스트 전용으로 취급됩니다.

비전 모델에는 다음을 명시하십시오.

models:
  - id: vision-preview
    input: [text, image]

제공자의 모든 모델이 이미지를 지원한다면 경로 수준의 defaultInput을 사용할 수 있습니다.

llm-pi-ai:
  providers:
    vision-gateway:
      defaultInput: [text, image]
      # ...

모델별 input은 defaultInput보다 우선합니다.

`compat`

OpenAI 호환 API이지만 일부 필드 또는 역할을 지원하지 않는 백엔드에 사용하는 호환성 옵션입니다.

문서화된 옵션은 다음과 같습니다.

compat:
  supportsDeveloperRole: false
  maxTokensField: max_tokens

supportsDeveloperRole: false: 백엔드가 developer 역할을 거부할 때 사용합니다.
maxTokensField: max_tokens: 이전 토큰 제한 필드 이름을 요구할 때 사용합니다.

compat는 제공자 전체 또는 개별 모델에 설정할 수 있습니다.

llm-pi-ai:
  providers:
    legacy-gateway:
      apiKeyEnv: LEGACY_API_KEY
      api: openai-completions
      baseURL: https://legacy.example/v1
      compat:
        supportsDeveloperRole: false
      models:
        - id: legacy-chat
          compat:
            maxTokensField: max_tokens

모델 목록 자동 가져오기

웹 UI에서 사용자 지정 제공자를 추가할 때 Fetch available models를 사용할 수 있습니다. 이 기능은 엔드포인트의 OpenAI 호환 GET /models 경로를 호출해 모델 목록을 채웁니다.

따라서 YAML을 작성하기 전에 먼저 다음 요청이 성공하는지 확인하는 것이 좋습니다.

curl http://localhost:11434/v1/models

API 키는 어디에 저장되는가

비밀 값은 $DSH_HOME/.credentials.yaml에 쓰기 전용으로 저장됩니다.

UI에서 키를 저장하면 dsh는 수정된 설명자만 반환하며, 실제 키 값은 다시 표시하지 않습니다. 반면 settings.yaml에는 다음과 같은 참조만 남습니다.

apiKeyEnv: GATEWAY_API_KEY

이 구조의 장점은 다음과 같습니다.

settings.yaml을 공유하거나 커밋할 때 키가 노출되지 않습니다.
제공자 설정을 바꾸지 않고 키만 교체할 수 있습니다.
환경별로 다른 키를 주입할 수 있습니다.

그래도 .credentials.yaml과 환경 변수는 비밀 정보로 취급하고, 저장소에 커밋하지 마십시오.

레시피 1: Ollama로 로컬 모델 실행

Ollama는 http://localhost:11434/v1에서 OpenAI 호환 API를 노출합니다. 자세한 내용은 Ollama의 OpenAI 호환성 가이드에서 확인할 수 있습니다.

다음 설정을 $DSH_HOME/settings.yaml에 추가합니다.

llm-pi-ai:
  providers:
    ollama-local:
      apiKeyEnv: OLLAMA_API_KEY
      api: openai-completions
      baseURL: http://localhost:11434/v1
      models:
        - id: gpt-oss:20b
        - id: qwen3

dsh 공식 제공자 문서에는 Ollama 전용 예시가 없습니다. 이 구성은 dsh의 사용자 지정 제공자 스키마와 Ollama의 문서화된 OpenAI 호환 엔드포인트를 결합한 방식입니다. 적용 전에는 설치 환경에서 반드시 테스트하십시오.

1단계: Ollama 실행 및 모델 준비

먼저 필요한 모델을 내려받습니다.

ollama pull gpt-oss:20b

설치된 모델 목록을 확인합니다.

ollama list

models[].id에는 ollama list에 표시되는 태그를 정확히 입력하십시오. 예를 들어 모델 태그가 gpt-oss:20b라면 YAML도 동일해야 합니다.

2단계: 더미 API 키 환경 변수 설정

Ollama는 로컬 API 키를 요구하지 않지만, dsh 제공자 스키마는 자격 증명 참조를 기대합니다. 따라서 더미 값을 설정합니다.

export OLLAMA_API_KEY=ollama

Ollama는 이 값을 무시합니다.

3단계: dsh에 연결하기 전에 API 확인

먼저 GET /models가 응답하는지 확인하십시오.

curl http://localhost:11434/v1/models

또는 Apidog에서 다음 URL을 호출할 수 있습니다.

http://localhost:11434/v1/models

모델 목록이 반환되면 다음을 확인한 것입니다.

Ollama 서버가 실행 중입니다.
baseURL이 올바릅니다.
dsh UI의 Fetch available models도 사용할 가능성이 높습니다.

로컬 GPT-OSS 실행 절차는 Ollama로 GPT-OSS 실행하기에서 더 자세히 확인할 수 있습니다.

로컬 모델 사용 시 기대치

에이전트 하네스는 도구 호출과 긴 컨텍스트를 많이 사용합니다. 작은 로컬 모델은 다음 용도에는 적합합니다.

플러그인 개발
도구 연결 테스트
프롬프트 흐름 확인
오프라인 반복 작업

다만 최신 대형 모델과 비교하면 계획 능력이 떨어지거나 도구 호출을 놓칠 수 있습니다. 실제 복잡한 작업에서는 더 강력한 모델로 전환하는 것이 적합할 수 있습니다.

레시피 2: 호스팅된 OpenAI 호환 엔드포인트 연결하기

호스팅된 제공자를 연결할 때는 단순히 “OpenAI 호환”이라고 주장하는 서비스보다, 엔드포인트와 인증 방법을 문서화한 제공자를 선택하는 편이 안전합니다.

Alibaba Cloud Model Studio(DashScope)는 Qwen 모델용 OpenAI 호환 엔드포인트를 문서화합니다. DashScope OpenAI 호환성 문서에 따르면 싱가포르 리전의 형식은 다음과 같습니다.

https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1

dsh 설정은 다음과 같습니다.

llm-pi-ai:
  providers:
    qwen-dashscope:
      apiKeyEnv: DASHSCOPE_API_KEY
      api: openai-completions
      baseURL: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
      models:
        - id: qwen3-max

적용 절차

{WorkspaceId}를 Model Studio 콘솔의 실제 워크스페이스 도메인으로 바꿉니다.
API 키를 환경 변수에 설정합니다.

   export DASHSCOPE_API_KEY="your-api-key"

공급업체의 모델 목록에서 현재 모델 ID를 확인합니다.
모델 ID를 models[].id에 입력합니다.
가능하다면 dsh에 추가하기 전에 GET /models로 엔드포인트를 검증합니다.

Qwen 모델 계층은 Qwen 3.8 API 가이드에서도 확인할 수 있습니다.

이 패턴은 OpenAI 호환 API를 문서화한 다른 제공자에도 적용됩니다.

Moonshot의 Kimi API
OpenRouter
vLLM 배포
사내 API 게이트웨이
지역별 모델 제공자

바뀌는 값은 보통 세 가지뿐입니다.

apiKeyEnv: PROVIDER_API_KEY
baseURL: https://provider.example/v1
models:
  - id: provider-model-id

Codex에서 오픈 소스 모델 구성하기를 사용해 본 적이 있다면, dsh의 YAML 블록은 Codex의 model_providers 설정과 유사한 역할을 합니다.

호스팅 엔드포인트에서 자주 필요한 설정

`developer` 역할 오류

제공자가 다음과 비슷한 오류를 반환할 수 있습니다.

Unsupported role: developer

이 경우 compat를 추가해 보십시오.

compat:
  supportsDeveloperRole: false

토큰 제한 필드 오류

백엔드가 최신 토큰 제한 필드를 지원하지 않는다면 다음 설정이 필요할 수 있습니다.

compat:
  maxTokensField: max_tokens

비전 모델에서 이미지가 무시되는 경우

호스팅 모델이 이미지 입력을 지원하더라도 dsh 설정에서 명시해야 합니다.

models:
  - id: vision-model-id
    input: [text, image]

레시피 3: 내장 카탈로그 제공자 사용

주류 클라우드 모델을 사용한다면 사용자 지정 YAML 블록이 항상 필요한 것은 아닙니다. dsh는 DeepSeek, Anthropic, OpenAI용 카탈로그 제공자를 제공합니다.

일반적인 흐름은 API 키를 추가하고 모델을 선택하는 방식입니다. 일부 카탈로그 제공자는 자체 인증 흐름을 사용합니다.

제공자 유형	인증 또는 설정 방식
Bedrock	AWS 자격 증명
Vertex	ADC 프로젝트
Azure	`api-version` 필요
Codex	OAuth 인증

카탈로그 제공자는 Claude 또는 GPT 같은 주류 모델을 빠르게 연결할 때 마찰이 적습니다. DeepSeek V4-Pro API는 하네스와 함께 2026년 8월에 출시되었으며, 세부 내용은 DeepSeek API 문서에서 확인할 수 있습니다.

반대로 사용자 지정 제공자는 다음과 같은 대상을 연결할 때 사용합니다.

로컬 런타임
사내 게이트웨이
지역별 제공자
OpenAI 호환 애그리게이터
카탈로그에 없는 호스팅 모델

모델 선택과 세션 동작

제공자를 추가하면 해당 모델을 선택할 수 있습니다. Settings → Models에서 모델을 선택하면 이후 생성되는 새 세션의 기본값이 됩니다.

다음 두 동작을 이해하고 사용하십시오.

기존 세션은 시작 시 모델을 유지합니다.

기본 모델을 변경해도 기존 세션의 모델 기록이나 현재 실행 중인 세션이 자동으로 바뀌지 않습니다.
기본 모델의 제공자를 삭제하면 새 모델을 선택할 때까지 입력이 차단됩니다.

dsh는 임의의 대체 모델을 추측하지 않고 명확한 오류를 표시합니다.

이 세션 고정 방식은 재현성에 중요합니다. 예를 들어 DeepSeek Harness와 Claude Code 비교처럼 여러 하네스를 비교할 때, 실행 중간에 모델이 바뀐 것이 아니라 하나의 모델을 기준으로 세션이 진행되었다고 신뢰할 수 있습니다.

일반적인 실패와 해결 방법

`baseURL`이 잘못되었거나 연결할 수 없음

가장 흔한 문제입니다. URL이 제공자가 기대하는 경로에서 끝나는지 확인하십시오.

일반 OpenAI 호환 API: 보통 /v1
DashScope: /compatible-mode/v1

dsh를 실행하기 전에 직접 모델 목록을 요청합니다.

curl \
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
  https://gateway.example/v1/models

Apidog 다운로드 후 같은 요청을 보내면 상태 코드, 응답 헤더, 오류 본문을 빠르게 확인할 수 있습니다. 하네스가 감싼 오류 메시지 대신 실제 API 응답을 보면 원인 파악이 쉬워집니다.

오프라인 개발 중이거나 제공자 API가 불안정하다면 /models와 /chat/completions 응답을 모의(mock)한 뒤, 개발 중에는 baseURL을 모의 서버로 지정할 수 있습니다.

환경 변수가 누락되었거나 비어 있음

apiKeyEnv는 환경 변수의 이름만 지정합니다. 변수를 생성하거나 값을 저장하지는 않습니다.

다음 설정이 있어도:

apiKeyEnv: GATEWAY_API_KEY

실행 환경에 변수가 없다면 요청은 인증 없이 전송되고 401 오류가 발생할 수 있습니다.

echo $GATEWAY_API_KEY

중요한 점은 dsh web을 실행한 동일한 컨텍스트에서 확인해야 한다는 것입니다. GUI, 서비스 관리자 또는 IDE에서 실행한 프로세스는 셸 프로필의 환경 변수를 상속하지 않을 수 있습니다.

이미지 입력이 작동하지 않음

이미지를 첨부했는데 모델이 인식하지 못하거나 API 오류가 발생한다면 모달리티 설정을 확인하십시오.

models:
  - id: vision-model
    input: [text, image]

모든 모델이 비전을 지원한다면 다음처럼 기본값을 설정할 수 있습니다.

llm-pi-ai:
  providers:
    vision-provider:
      defaultInput: [text, image]

역할 또는 토큰 파라미터 오류

지원되지 않는 역할이나 토큰 제한 필드를 언급하는 오류는 compat 설정 대상일 수 있습니다.

compat:
  supportsDeveloperRole: false
  maxTokensField: max_tokens

두 옵션은 문서화된 호환성 스위치입니다. 하나씩 적용하며 제공자 API가 어떤 필드를 거부하는지 확인하십시오.

어제까지 작동하던 설정이 깨짐

dsh는 개발자 프리뷰입니다. 다음 운영 원칙을 적용하십시오.

배포하는 버전을 고정합니다.
업그레이드 전에 릴리스 노트를 읽습니다.
설정 스키마 변경을 예상합니다.
블로그 글보다 공식 deepseek-harness 리포지토리를 우선합니다.

모델 제공자 구성은 사용자 지정의 절반입니다. 나머지 절반은 에이전트가 호출하는 도구입니다. API 워크플로를 하네스에 연결하려면 DeepSeek Harness에서 Apidog CLI 사용하기를 참고하십시오.

FAQ

DeepSeek Harness는 Ollama를 공식 지원하나요?

공식 제공자 문서에는 Ollama가 명시적으로 언급되어 있지 않습니다. 다만 dsh는 openai-completions 프로토콜을 사용하는 엔드포인트를 지원하며, Ollama는 http://localhost:11434/v1에서 OpenAI 호환 API를 문서화합니다.

이 글의 Ollama 레시피는 문서화된 두 구성을 결합한 것입니다. dsh는 개발자 프리뷰이므로 설치한 버전에서 직접 테스트하십시오.

dsh는 API 키를 어디에 저장하나요?

$DSH_HOME/.credentials.yaml에 쓰기 전용으로 저장합니다.

UI는 저장 후 수정된 설명자만 보여주며, settings.yaml에는 apiKeyEnv 같은 참조만 남습니다. 제공자 설정에 일반 텍스트 키가 포함되지는 않습니다.

세션마다 다른 모델을 사용할 수 있나요?

가능합니다. 모델 선택은 새 세션의 기본값에만 영향을 줍니다. 기존 세션은 시작 당시 사용한 모델을 유지합니다.

예를 들어 일상적인 세션에는 DeepSeek V4-Flash를 사용하고, 어려운 작업을 위해 기본 모델을 더 강력한 모델로 변경해도 기존 세션은 영향을 받지 않습니다.

사용자 지정 엔드포인트가 `curl`에서는 없던 오류를 반환합니다. 어떻게 해결하나요?

정확한 요청 페이로드를 비교하십시오. 하네스가 백엔드에서 허용하지 않는 developer 역할이나 최신 토큰 제한 필드를 보낼 수 있습니다.

먼저 다음 호환성 설정을 적용해 보십시오.

compat:
  supportsDeveloperRole: false
  maxTokensField: max_tokens

API 클라이언트에서 하네스와 유사한 헤더와 요청 본문을 재현하면, 백엔드가 거부하는 필드를 더 빠르게 찾을 수 있습니다.

DeepSeek Harness에서 Apidog CLI 사용법

Rihpig — Thu, 20 Aug 2026 07:59:26 +0000

DeepSeek Harness는 하나의 루프로 동작합니다. 에이전트는 작업 공간을 읽고, 파일을 편집하고, bash 도구로 명령을 실행한 뒤, 출력에 따라 다음 작업을 결정합니다. 그렇다면 API 테스트도 이 루프에 포함되어야 합니다. GUI에서 누군가 직접 클릭해야 하는 Apidog 테스트 대신, CLI로 시나리오를 실행하면 에이전트가 단위 테스트와 같은 방식으로 결과를 읽고 실패한 코드를 수정할 수 있습니다.

지금 Apidog 사용해 보기

해결책은 간단합니다. npm 패키지인 apidog-cli를 설치하고, Apidog에서 만든 테스트 시나리오를 터미널에서 실행하도록 DeepSeek Harness에 지시하면 됩니다.

에이전트는 다음과 같은 흐름으로 동작합니다.

apidog run 명령 실행
CLI 출력과 종료 코드 확인
종료 코드가 0이면 다음 작업 진행
종료 코드가 0이 아니면 실패한 어설션 확인
코드 수정 후 시나리오 재실행

이 방식은 에이전트가 핸들러 코드와 응답 형식을 반복해서 추론하는 데 쓰는 컨텍스트를 줄입니다. CLI가 “API가 올바른가?”라는 질문을 종료 코드와 테스트 결과로 반환하므로, 에이전트는 분석보다 수정 작업에 집중할 수 있습니다.

이 글에서는 일반 설치 가이드보다 DeepSeek Harness 통합에 초점을 맞춥니다. 아직 CLI를 설치하지 않았다면 먼저 AI 코딩 에이전트로 Apidog CLI를 설치하는 방법을 참고하세요. 아래 내용은 apidog --version이 정상적으로 버전을 출력하고, 현재 컴퓨터가 Apidog에 인증되어 있다는 전제에서 진행합니다.

이 문서가 다루는 DeepSeek Harness

명령줄에서 dsh로 실행하는 DeepSeek Harness는 DeepSeek이 2026년 8월 13일 V4-Pro와 함께 API에 출시한 오픈 소스 에이전트 Harness입니다.

라이선스: MIT
소스: github.com/deepseek-ai/deepseek-harness
실행 명령: npx @deepseek-ai/dsh web
로컬 UI: http://127.0.0.1:3080

웹 UI에서 프로젝트 디렉터리를 작업 공간으로 선택하면 에이전트는 해당 디렉터리 안에서 파일을 읽고 편집하며 명령을 실행합니다. 활성 권한 정책에 따라 특정 작업은 실행 전 승인이 필요할 수 있습니다.

다만 DeepSeek Harness는 개발자 프리뷰입니다. README에서 호환성을 깨뜨리는 변경이 발생할 수 있다고 경고하므로, 파일 이름이나 설정 키가 동작하지 않을 때는 공식 리포지토리 문서를 다시 확인하세요.

DeepSeek Harness의 전체 개요는 DeepSeek Harness란 무엇인가, 기존 도구와의 비교는 DeepSeek Harness vs Claude Code에서 확인할 수 있습니다.

단계 1: `AGENTS.md`에 Apidog CLI 명령 추가

DeepSeek Harness는 @deepseek-ai/dsh-agent-instructions 플러그인을 통해 작업 공간 지침을 읽습니다.

설정 카탈로그에 따르면, 지침 로더는 세션 작업 디렉터리에서 프로젝트 루트까지 상위 디렉터리를 탐색하며 다음 파일을 읽습니다.

AGENTS.md
CLAUDE.md — AGENTS.md가 없을 때 대체
AGENTS.local.md
CLAUDE.local.md
$DSH_HOME/AGENTS.md — 기본적으로 ~/.dsh/AGENTS.md

즉, 이미 Codex용 AGENTS.md 또는 Claude Code용 CLAUDE.md를 사용 중이라면 별도 설정 없이 DeepSeek Harness가 해당 파일을 읽을 수 있습니다.

프로젝트의 AGENTS.md에 다음 블록을 추가하세요.

## API testing with the Apidog CLI
- To test the API, run the Apidog scenario. Do not click through the GUI.
- Command: apidog run -t <scenario_id> -e <env_id> -r cli
- Exit code 0 means every assertion passed. Non-zero means a failure; read the report and fix the code.
- The machine is already authenticated. Never add an --access-token flag and never put a token in this file.

실제 프로젝트에서는 <scenario_id>와 <env_id>를 Apidog에서 발급된 값으로 교체합니다.

예시는 다음과 같습니다.

## API testing with the Apidog CLI
- API 변경 후 반드시 다음 테스트를 실행한다.
- Command: apidog run -t 123456 -e 789012 -r cli
- 종료 코드가 0이면 테스트가 통과한 것이다.
- 종료 코드가 0이 아니면 CLI 보고서를 읽고 실패한 코드와 테스트를 수정한다.
- 이 머신은 이미 인증되어 있다. --access-token을 추가하거나 토큰을 이 파일에 기록하지 않는다.

이 규칙을 채팅 메시지가 아니라 리포지토리의 AGENTS.md에 넣는 것이 중요합니다. 세션 채팅에 입력한 시나리오 ID는 세션 종료 후 사라지지만, 리포지토리에 기록한 명령은 팀원이 프로젝트를 복제하거나 새 세션을 시작해도 유지됩니다.

여러 프로젝트에서 공통 규칙을 사용한다면 ~/.dsh/AGENTS.md에 다음과 같은 전역 지침을 둘 수 있습니다.

- API 변경이 있으면 프로젝트에 정의된 apidog run 명령을 실행한다.
- 테스트 실패 시 종료 코드와 실패한 어설션을 확인한 뒤 코드를 수정한다.

프로젝트별 AGENTS.md에는 실제 시나리오 및 환경 ID를 기록하세요.

단계 2: Apidog에서 실행 명령 복사

시나리오 ID와 환경 ID를 직접 추측하지 마세요.

Apidog에서 다음 순서로 명령을 가져옵니다.

테스트 시나리오 열기
CI/CD 탭으로 이동
생성된 CLI 명령 복사
AGENTS.md에 붙여넣기

명령은 일반적으로 다음 형식입니다.

apidog run -t 123456 -e 789012 -r cli

각 옵션의 의미는 다음과 같습니다.

옵션	설명
`-t`	테스트 시나리오 ID
`-e`	환경 ID
`-r cli`	결과를 터미널 인라인 출력으로 반환하는 리포터

에이전트가 잘못된 ID를 추측하지 않도록, Apidog의 CI/CD 탭에서 복사한 명령을 그대로 사용하세요.

단계 3: DeepSeek Harness에서 테스트 실행

dsh 웹 UI에서 프로젝트 작업 공간을 선택한 뒤 세션을 시작합니다. AGENTS.md가 로드되었다면 에이전트는 Apidog CLI 명령을 이미 알고 있어야 합니다.

다음과 같이 요청할 수 있습니다.

Apidog 테스트 시나리오를 실행하고 종료 코드를 알려주세요.

또는 API 변경까지 포함해 요청할 수 있습니다.

체크아웃 핸들러를 수정한 뒤 AGENTS.md에 정의된 Apidog 테스트를 실행하세요.
실패하면 보고서를 읽고 코드를 수정한 뒤 다시 실행하세요.

DeepSeek Harness의 기본 bash 도구는 명령마다 새 셸을 실행합니다. 따라서 다음과 같은 두 단계 호출은 의도대로 동작하지 않을 수 있습니다.

cd apps/api

apidog run -t 123456 -e 789012 -r cli

두 번째 명령은 첫 번째 명령의 cd 상태를 유지하지 않습니다.

시나리오를 특정 하위 디렉터리에서 실행해야 한다면, AGENTS.md에 전체 명령을 한 줄로 작성하세요.

- Command: cd apps/api && apidog run -t 123456 -e 789012 -r cli

또는 Harness가 제공하는 경우 bash 도구의 workdir 매개변수를 사용하세요.

도구 카탈로그에 따르면, 명령 실패 시 Harness는 다음과 같은 마커를 반환합니다.

[exit code: 1]

긴 로그가 잘리더라도 이 마커를 통해 테스트 성공 여부를 확인할 수 있습니다.

권한 정책에 따라 apidog run 실행 전 승인을 요청받을 수도 있습니다. 사용자 가이드에 따라 웹 UI에서 요청을 승인하면 됩니다.

단계 4: CLI 보고서 읽기

테스트가 실패했을 때는 -r cli 출력이 핵심입니다. CLI 보고서에는 일반적으로 다음 정보가 포함됩니다.

실행된 요청
각 요청의 어설션 결과
예상 상태 코드와 실제 상태 코드
예상 필드와 실제 응답 필드
실패한 어설션

예를 들어 다음과 같은 실패를 확인할 수 있습니다.

Expected status code: 200
Actual status code: 500

또는:

Assertion failed: response.body.total is required

이 정보가 있으면 에이전트는 사용자 설명 없이도 실패한 핸들러, 응답 DTO 또는 데이터 변환 로직을 찾아 수정할 수 있습니다.

브라우저에서 열거나 팀원과 공유할 HTML 보고서도 필요하다면 html 리포터를 추가하세요.

apidog run -t 123456 -e 789012 -r cli,html

html 리포터는 ./apidog-reports에 자체 포함형 보고서를 생성합니다. 다만 에이전트가 다음 수정 작업을 결정하려면 터미널 출력도 필요하므로 cli 리포터는 유지하는 것이 좋습니다.

전체 루프: 수정, 테스트, 수정

설정이 완료되면 API 작업 흐름은 다음과 같이 바뀝니다.

에이전트가 체크아웃 핸들러 수정
apidog run -t 123456 -e 789012 -r cli 실행
종료 코드와 어설션 결과 확인
통과하면 다음 작업 진행
실패하면 실패한 필드, 상태 코드 또는 응답 값 확인
코드 수정
테스트 재실행

예를 들어 테스트가 다음과 같이 실패했다고 가정해 보겠습니다.

Expected status: 200
Actual status: 500
[exit code: 1]

에이전트는 단순히 “코드가 올바르게 보인다”라고 판단하지 않고, 실제 API 계약 테스트 결과를 기준으로 핸들러를 다시 검토할 수 있습니다.

또 다른 실패 예시는 다음과 같습니다.

Expected field: total
Actual response: field missing
[exit code: 1]

이 경우 에이전트는 응답 객체에 total이 누락되었는지, 직렬화 과정에서 필드가 제거되었는지, 잘못된 DTO를 반환하고 있는지 확인한 뒤 수정하고 시나리오를 다시 실행합니다.

핵심은 역할 분리입니다.

DeepSeek Harness: 코드 읽기, 수정, 명령 실행
Apidog CLI: API 계약 및 시나리오 검증
Apidog: 테스트 시나리오의 시각적 작성과 관리

에이전트는 API가 동작하는지 확인하기 위해 모든 라우트와 핸들러 파일을 반복해서 해석할 필요가 없습니다. Apidog 시나리오가 이미 기대 동작을 정의하고 있으므로, 에이전트는 결정론적인 CLI 결과를 바탕으로 수정 작업을 진행할 수 있습니다.

dsh가 실제로 테스트를 실행했는지 확인하기

에이전트의 요약만 믿지 말고, 다음 세 가지를 확인하세요.

1. 실제 bash 호출 확인

dsh 웹 UI는 에이전트의 도구 호출과 출력을 세션에 표시합니다.

다음과 같은 실제 명령이 표시되는지 확인하세요.

apidog run -t 123456 -e 789012 -r cli

에이전트가 “테스트를 실행했다”고 말하지만 실제 bash 호출이 없다면 테스트는 실행되지 않은 것입니다. 이 경우 다음처럼 요청하세요.

Apidog 테스트를 다시 실행하고, 원시 CLI 출력과 종료 코드를 보여주세요.

2. 종료 코드 확인

직접 종료 코드를 물어보세요.

방금 실행한 apidog run 명령의 종료 코드는 무엇이었나요?

다음 값이 기준입니다.

0: 모든 어설션 통과
0 이외의 값: 테스트 실패 또는 실행 문제 발생

에이전트가 “테스트 통과”라고 요약했더라도 출력에 [exit code: 1]이 있다면 실패로 처리해야 합니다.

3. 실제 시나리오 ID와 환경 ID 확인

다음과 같은 오류는 대개 잘못된 ID를 사용했음을 의미합니다.

Scenario not found

이 경우 다음 세 위치의 값을 비교하세요.

Apidog CI/CD 탭에서 복사한 명령
리포지토리의 AGENTS.md
dsh가 실제로 실행한 bash 명령

특히 -t와 -e 값이 일치해야 합니다. AGENTS.md에 기록된 명령을 기준으로 삼고, 에이전트가 임의로 생성하거나 기억한 값은 신뢰하지 않는 것이 안전합니다.

선택 사항: API 사양 접근을 위한 Apidog MCP 서버 추가

Apidog CLI는 검증에 적합합니다. 반면 에이전트가 코드를 작성하기 전에 API 스키마와 엔드포인트 정의를 읽게 하려면 MCP가 필요합니다.

2026년 8월 말 기준으로 DeepSeek Harness 핵심 README와 사용자 가이드에는 MCP 지원이 문서화되어 있지 않습니다. 대신 커뮤니티 플러그인인 hyqhyq3/dsh-mcp-manager를 사용할 수 있습니다.

이 플러그인은 다음 기능을 제공합니다.

설정 화면에 MCP 관리 페이지 추가
원격 HTTP MCP 서버 지원
로컬 stdio MCP 서버 지원
mcp__<name>__* 형식의 도구 등록
<workspace>/.dsh/dshmm/mcp.json에서 프로젝트별 서버 설정 로드

이를 통해 Apidog MCP 서버를 연결하면, 에이전트는 테스트 실패 후뿐 아니라 핸들러를 작성하기 전에도 API 사양을 조회할 수 있습니다.

다만 이는 커뮤니티 플러그인과 개발자 프리뷰 호스트를 함께 사용하는 구성입니다. 양쪽 업데이트로 인해 동작이 바뀔 수 있으므로, 기본 경로는 여전히 CLI로 유지하는 것이 좋습니다.

기본 경로: Apidog CLI로 테스트 실행
추가 경로: MCP로 API 스키마와 엔드포인트 조회

개발자 프리뷰 주의 사항

DeepSeek Harness는 빠르게 변경될 수 있습니다. 특히 다음 요소는 변경 가능성이 높습니다.

지침 파일 탐색 규칙
AGENTS.md 및 CLAUDE.md 우선순위
bash 도구의 샌드박스 동작
권한 승인 흐름
MCP 플러그인 호환성

구체적인 설정이 바뀌더라도 핵심 패턴은 유지됩니다.

규칙 파일에 API 검증 명령 기록
에이전트가 해당 명령 실행
CLI가 명확한 종료 코드 반환
에이전트가 실패 로그를 바탕으로 코드 수정
수정 후 다시 검증

이 패턴은 Claude Code에서 Apidog CLI 사용하기와 다른 Harness 환경에서도 적용할 수 있습니다. 에이전트는 명령 출력 해석에는 강하지만, 실제 검증 명령 없이 결과를 신뢰하기는 어렵기 때문입니다.

Apidog를 다운로드한 뒤 테스트 시나리오 하나를 만들고, CI/CD 탭에서 apidog run 명령을 복사해 AGENTS.md에 추가해 보세요. 다음에 DeepSeek Harness가 API 코드를 수정할 때, 완료되었다고 말하기 전에 실제 시나리오로 결과를 확인하게 할 수 있습니다.

FAQ

DeepSeek Harness는 기본적으로 `AGENTS.md`를 읽나요?

예. @deepseek-ai/dsh-agent-instructions 플러그인은 프로젝트 루트와 세션 작업 디렉터리 상위 경로에서 AGENTS.md를 읽습니다. 파일이 없으면 CLAUDE.md를 대체 파일로 사용하며, AGENTS.local.md, CLAUDE.local.md, ~/.dsh/AGENTS.md도 로드할 수 있습니다.

다른 에이전트용으로 이미 AGENTS.md를 유지하고 있다면 dsh는 별도 변환 없이 해당 파일을 활용할 수 있습니다.

dsh에서 Apidog CLI를 사용하려면 유료 DeepSeek 플랜이 필요한가요?

아니요. Harness는 MIT 라이선스 기반 오픈 소스이며 사용자가 모델을 선택합니다. 카탈로그 공급자는 Anthropic, OpenAI, Bedrock, Vertex, Azure를 다루며, 사용자 지정 게이트웨이는 settings.yaml으로 설정할 수 있습니다.

관련 내용은 DeepSeek Harness에서 모든 모델을 실행하는 방법에서 확인할 수 있습니다.

Apidog CLI 자체는 무료 npm 패키지입니다. 필요한 것은 특정 DeepSeek 플랜이 아니라 Apidog 테스트 시나리오와 인증입니다.

두 번째 명령이 첫 번째 명령의 디렉터리 변경을 잊는 이유는 무엇인가요?

기본 dsh bash 도구가 각 호출을 새 셸에서 실행하기 때문입니다. 첫 번째 호출의 cd는 두 번째 호출에 유지되지 않습니다.

다음 중 하나를 사용하세요.

cd apps/api && apidog run -t 123456 -e 789012 -r cli

또는 Harness 도구의 workdir 매개변수를 전달하세요.

dsh가 매번 승인 요청 없이 시나리오를 실행할 수 있나요?

활성 권한 정책에 따라 다릅니다. 웹 UI는 승인이 필요한 작업 전에 요청을 표시할 수 있습니다. 정책 수준은 배포 구성에 따라 달라질 수 있으므로 현재 환경의 설정을 확인하세요.

스테이징 환경에 대해 읽기 중심으로 실행하는 apidog run은 승인 가능한 작업의 일반적인 예입니다.

DeepSeek Harness vs Claude Code: 당신의 기술 스택에 맞는 코딩 에이전트는?

Rihpig — Thu, 20 Aug 2026 06:05:29 +0000

DeepSeek Harness vs Claude Code: 개발자 관점의 실전 비교

DeepSeek Harness(dsh)는 2026년 8월 13일 출시되었습니다. VentureBeat의 출시 기사 헤드라인은 dsh를 DeepSeek V4-Pro와 함께 API로 출시된 “Claude Code의 오픈소스 경쟁자”라고 소개했습니다. 출시 일주일 후 GitHub 리포지토리는 8월 20일 기준 약 16.9만 개의 별을 기록했습니다.

오늘 Apidog를 사용해 보세요

하지만 별 수만으로는 실제 선택에 필요한 답을 얻기 어렵습니다.

내 코딩 에이전트를 DeepSeek Harness에서 실행해야 할까?
Claude Code를 계속 사용하는 편이 나을까?
모델 선택권, 권한 관리, MCP, 비용은 어떻게 다를까?

두 도구는 방향이 다릅니다. DeepSeek Harness는 플러그인 커널과 로컬 웹 UI를 기반으로 한 MIT 라이선스 개발자 프리뷰입니다. Claude Code는 스킬, 훅, 네이티브 MCP, 서브 에이전트, 여러 실행 인터페이스를 제공하는 독점 제품입니다.

이 글에서는 라이선스, 인터페이스, 모델 선택권, 가격, 성숙도, 확장성, 권한, MCP를 실제 사용 관점에서 비교합니다. 허구의 벤치마크나 주관적인 성능 주장은 제외하고, 현재 문서화된 기능만 다룹니다.

dsh가 처음이라면 먼저 DeepSeek Harness가 무엇이며 어떻게 작동하는지를 확인한 뒤 돌아오세요.

💡 두 에이전트의 공통점은 API 코드를 작성한다는 것입니다. 에이전트가 참고하는 API 사양이 부정확하면 결과도 부정확해집니다. Apidog는 선택한 에이전트와 관계없이 API 사양을 테스트하고 최신 상태로 유지하는 데 사용할 수 있습니다.

한눈에 비교하기

항목	DeepSeek Harness (dsh)	Claude Code
라이선스	MIT, GitHub에 소스 공개	독점, Anthropic 상업 약관
출시 시점/성숙도	2026년 8월 13일 출시, 개발자 프리뷰	일반 출시, 성숙한 제품
안정성	README에 호환성을 깨뜨리는 변경 사항에 대한 경고	안정적인 릴리스 채널과 버전 관리 설정
인터페이스	`127.0.0.1:3080` 로컬 웹 UI, 헤드리스 프로필 기반 CLI	터미널 CLI, VS Code, JetBrains, 데스크톱 앱, 웹, 모바일
모델	DeepSeek, Anthropic, OpenAI, Bedrock, Vertex, Azure 및 OpenAI 호환 엔드포인트	Claude 모델만 사용
가격	하네스 무료, 연결한 API의 토큰 비용 지불	Claude Pro/Max 구독 또는 콘솔 기반 사용량 청구
확장성	Cordis 플러그인 커널, 커뮤니티 `dsh-plugin` 토픽	플러그인, 스킬, 훅, 서브 에이전트, Agent SDK
권한	활성 권한 정책에 따른 웹 UI 승인 프롬프트	6가지 권한 모드와 세분화된 허용/거부 규칙
MCP	커뮤니티 플러그인 `dsh-mcp-manager`	네이티브 지원

표만으로는 실제 설정과 운영 방식의 차이를 알기 어렵습니다. 이제 항목별로 살펴보겠습니다.

오픈소스와 독점 모델: MIT 라이선스가 주는 것

DeepSeek Harness는 MIT 라이선스를 사용하며, 서드파티 종속성은 THIRD_PARTY_NOTICES.md에 기록되어 있습니다.

따라서 다음 작업이 가능합니다.

에이전트 루프와 플러그인 커널 코드 검토
필요한 부분 포크 또는 패치
상업 제품에 통합
네트워크 요청과 데이터 흐름 감사
자체 인프라에 맞춘 동작 수정

규정 준수가 중요한 팀이나, 공급업체가 기능을 중단할 가능성을 줄이고 싶은 플랫폼 팀에게는 큰 장점입니다.

Claude Code는 반대입니다. Anthropic의 공개 리포지토리에는 다음과 같은 안내가 있습니다.

© Anthropic PBC. 모든 권리 보유. 사용은 Anthropic의 상업 서비스 약관에 따릅니다.

공개 리포지토리는 이슈와 문서를 위한 공간이며, 포크할 수 있는 에이전트 소스 코드를 제공하지 않습니다. 따라서 Claude Code를 사용할 때는 완성된 제품과 이용 약관에 의존하게 됩니다.

다만 오픈소스가 항상 더 지속 가능한 것은 아닙니다. dsh의 MIT 라이선스는 사용, 수정, 배포에 대한 권리를 제공하지만 프로젝트가 장기적으로 유지된다는 보장은 아닙니다. 특히 dsh는 출시된 지 일주일밖에 되지 않은 개발자 프리뷰라는 점을 고려해야 합니다.

인터페이스: 로컬 웹 UI와 멀티플랫폼 지원

DeepSeek Harness 실행하기

dsh의 기본 진입점은 로컬 웹 UI입니다.

npx @deepseek-ai/dsh web

명령을 실행하면 http://127.0.0.1:3080에서 웹 UI가 시작되고 브라우저가 열립니다. 브라우저를 자동으로 열지 않으려면 다음과 같이 실행합니다.

npx @deepseek-ai/dsh web --no-open

웹 UI에서 작업 공간을 선택하고, dsh를 실행한 프로젝트 디렉터리를 지정한 뒤 작업을 진행합니다. UI는 호스팅 서비스가 아니라 로컬 장치에서 실행됩니다.

dsh는 프로필 기반 CLI 모드도 제공합니다.

dsh --profile <name>

프로필은 $DSH_HOME/profiles/<name> 아래에서 시작됩니다. 헤드리스 프로필은 영구 세션을 실행하고 최종 답변을 출력한 뒤 종료하는 방식으로 자동화에 사용할 수 있습니다.

관련 CLI 동작은 CLI README에서 확인할 수 있습니다.

dsh web은 웹 프로필의 단축 명령이며, dsh plugin은 pnpm을 통해 프로필 플러그인 관리를 전달합니다.

Claude Code 실행하기

Claude Code는 터미널 중심으로 시작해 다음 인터페이스로 확장되었습니다.

터미널 CLI
VS Code 확장
JetBrains 확장
독립형 데스크톱 앱
웹 브라우저
모바일 지원

자세한 내용은 공식 문서를 참고하세요.

헤드리스 실행은 CI, cron, 셸 파이프라인에 연결할 때 유용합니다.

claude -p "프로젝트의 테스트 실패 원인을 분석하고 수정안을 제안해줘"

하나의 기기에서 하나의 프로젝트에 집중한다면 dsh의 로컬 웹 UI가 간단합니다. 반대로 IDE, 터미널, CI, 모바일을 오가며 작업한다면 Claude Code의 인터페이스 범위가 더 넓습니다.

모델 선택권: dsh의 가장 큰 차이

두 도구의 철학이 가장 크게 갈리는 부분은 모델 선택권입니다.

dsh는 모델에 종속되지 않도록 설계되었습니다. 제공자 문서에 따르면 다음 제공자를 사용할 수 있습니다.

DeepSeek
Anthropic
OpenAI
Amazon Bedrock
Google Vertex
Microsoft Azure
OpenAI 호환 엔드포인트

사용자 지정 OpenAI 호환 엔드포인트는 $DSH_HOME/settings.yaml에 등록할 수 있습니다.

providers:
  my-provider:
    apiKeyEnv: MY_PROVIDER_API_KEY
    api: openai-completions
    baseURL: https://example.com/v1
    models:
      - name: my-model

API 키는 별도의 .credentials.yaml 파일에 둘 수 있으므로 설정 파일을 공유할 때 인증 정보를 분리할 수 있습니다.

이 구조를 사용하면 다음과 같은 구성이 가능합니다.

DeepSeek 자체 모델 사용
경쟁 연구소의 API 연결
사내 OpenAI 호환 모델 서버 연결
자체 GPU에서 실행하는 양자화 모델 연결

전체 설정은 DeepSeek Harness에서 모든 모델을 실행하는 방법에서 확인할 수 있습니다.

Claude Code는 Claude 모델만 실행합니다. Anthropic API 대신 Amazon Bedrock, Google Cloud의 에이전트 플랫폼, Microsoft Foundry를 통해 추론을 라우팅할 수 있지만 모델 자체는 Claude입니다.

따라서 다음처럼 선택하면 됩니다.

여러 모델을 비교하거나 교체해야 한다면 dsh
하네스와 모델이 긴밀하게 통합된 경험을 원한다면 Claude Code

모델 종속이 비용과 유연성에 미치는 영향을 중요하게 생각하는지에 따라 판단하면 됩니다.

가격: 토큰당 비용과 구독

dsh 하네스 자체는 무료입니다. 실제 비용은 연결한 모델 API에서 발생합니다.

DeepSeek API를 사용한다면 DeepSeek의 토큰당 요금을 지불합니다. dsh와 같은 날 출시된 V4-Pro는 VentureBeat 보도에 따르면 이전 버전보다 높은 가격으로 출시되었습니다. DeepSeek V4-Pro-0813 API 사용 가이드에서는 모델 ID와 요청 형식을 다룹니다.

토큰당 요금의 특징은 다음과 같습니다.

사용하지 않으면 비용이 발생하지 않음
실제 사용량과 비용의 관계가 명확함
집중적인 에이전트 세션에서는 토큰 사용량이 커질 수 있음
고정된 비용 상한선이 없음

Claude Code는 주로 다음 방식으로 결제합니다.

Claude Pro: 월 $20
Claude Max: 월 $100 또는 $200
Claude Console을 통한 사용량 기반 API 청구

구독은 토큰당 청구보다 예측하기 쉬운 대신 사용량 제한이 있습니다. Anthropic은 2026년 7월 주간 제한을 50% 인상했으며, 자세한 내용은 Claude Code 주간 제한 인상에 대한 기사에서 확인할 수 있습니다.

대략적인 기준은 다음과 같습니다.

간헐적이거나 가벼운 사용: 토큰당 요금이 유리할 수 있음
매일 집중적으로 사용: 고정 구독이 유리할 수 있음
Anthropic 모델을 사용하되 하네스 선택권이 필요함: dsh에서 Anthropic API 사용 가능

성숙도: 개발자 프리뷰와 제품 생태계

dsh는 개발자 프리뷰입니다. README에는 호환성을 깨뜨리는 변경 사항이 있을 수 있다고 명시되어 있습니다.

따라서 dsh에 워크플로우를 구축할 때는 다음을 예상해야 합니다.

설정 형식이 변경될 수 있음
플러그인을 다시 작성해야 할 수 있음
문서가 변경되거나 부족할 수 있음
다음 버전에서 기존 자동화가 동작하지 않을 수 있음

이는 dsh의 단점이라기보다 프리뷰 단계의 특성입니다. 다만 프로덕션 워크플로우를 안정적으로 유지해야 한다면 중요한 위험 요소입니다.

Claude Code는 2025년 초부터 개발자에게 제공되어 왔으며, 다음 기능을 포함한 성숙한 생태계를 갖추고 있습니다.

CLAUDE.md 프로젝트 메모리
자동 메모리
재사용 가능한 워크플로우를 위한 스킬
에이전트 작업 전후에 셸 명령을 실행하는 훅
리드 에이전트와 서브 에이전트
커스텀 에이전트를 위한 Agent SDK
GitHub Actions 및 GitLab CI/CD 통합
예약 실행 루틴

관련 비교는 Claude Code와 Codex CLI 비교에서도 확인할 수 있습니다.

dsh는 짧은 기간에 약 16.9만 개의 별과 1.81만 개의 포크를 기록했습니다. 8월 20일 기준 수치이며, 커뮤니티의 관심과 성장 가능성을 보여줍니다. 하지만 현재 선택 기준은 명확합니다.

실험과 커스터마이징: dsh
안정성과 문서화된 생태계: Claude Code

확장성: 플러그인 커널과 확장 지점

두 도구 모두 확장할 수 있지만, 확장 방식이 다릅니다.

dsh: 코어 자체가 플러그인 구조

dsh는 Cordis 플러그인 커널을 기반으로 구축되었습니다. 모델 어댑터, 도구 레지스트리, 세션 로그, 에이전트 루프까지 교체 가능한 플러그인으로 구성됩니다.

예를 들어 기본 에이전트 루프의 동작이 요구사항에 맞지 않는다면 루프 자체를 교체하는 방향으로 확장할 수 있습니다.

커뮤니티 플러그인은 GitHub의 dsh-plugin 토픽에서 찾을 수 있습니다. 데스크톱 래퍼, 컨텍스트 관리자, 비전 라우터 같은 비공식 프로젝트도 이 구조를 활용할 수 있습니다.

Claude Code: 안정적인 경계에서 확장

Claude Code는 코어 루프를 수정하는 대신 다음 확장 지점을 제공합니다.

플러그인
스킬
훅
MCP 서버
서브 에이전트
Agent SDK

대부분의 팀에는 이 방식이 더 적합합니다. 코어를 직접 수정하지 않기 때문에 업그레이드 시 사용자 지정이 깨질 가능성을 줄일 수 있습니다.

반면 에이전트 엔진 자체를 다시 설계하려는 경우에는 dsh가 더 많은 자유를 제공합니다.

권한 관리: 승인 정책과 세분화된 모드

파일을 편집하고 명령을 실행하는 에이전트에는 권한 제어가 필요합니다.

dsh 웹 UI는 활성 권한 정책에 따라 승인이 필요한 작업 전에 승인 요청을 표시합니다. 다만 현재 공개 문서에서는 정책 수준과 각 정책의 정확한 의미가 충분히 자세히 설명되어 있지 않습니다.

Claude Code의 권한 시스템은 더 세분화되어 있습니다. 문서화된 권한 모드는 다음과 같습니다.

default
acceptEdits
plan
auto
dontAsk
bypassPermissions

또한 도구와 명령별 허용·거부 규칙, 작업 디렉터리 경계, 조직 전체에 적용할 수 있는 관리형 정책을 제공합니다.

예를 들어 plan 모드는 파일을 수정하지 않고 탐색과 계획에 집중하게 할 수 있습니다. bypassPermissions는 샌드박스 컨테이너와 함께 사용하는 시나리오를 위한 모드입니다.

다음 요구사항이 있다면 현재는 Claude Code가 더 적합합니다.

규제 대상 코드베이스
팀 단위의 세밀한 권한 관리
CI 환경에서의 에이전트 자율성
관리자가 통제하는 정책
명확하게 문서화된 승인 흐름

MCP: 네이티브 지원과 커뮤니티 플러그인

모델 컨텍스트 프로토콜(MCP)은 에이전트가 데이터베이스, 이슈 트래커, API 사양 같은 외부 시스템에 접근하는 표준 방식입니다.

Claude Code는 MCP를 네이티브로 지원합니다. 서버 연결과 도구 사용이 공식 흐름에 포함되어 있으며, MCP 도구도 다른 도구와 동일한 권한 규칙을 적용받습니다.

dsh의 MCP 지원은 현재 코어 기능이 아닙니다. 대신 커뮤니티 플러그인인 dsh-mcp-manager를 사용할 수 있습니다. 이 플러그인은 다음 기능을 제공합니다.

MCP 설정 페이지
원격 HTTP 서버 연결
로컬 stdio 서버 연결
OAuth 및 정적 토큰 처리
프로젝트별 서버 설정
mcp__<name>__* 형식의 도구 등록

기능은 동작하지만 공식 코어가 아니라 커뮤니티에서 유지보수됩니다. 따라서 dsh 프리뷰의 변경 위험과 플러그인 유지보수 위험을 함께 고려해야 합니다.

API 개발에서 MCP가 중요한 이유

API 코드를 생성할 때 에이전트가 실제 API 사양을 참조하지 않으면 다음 문제가 발생할 수 있습니다.

필드 이름 오류
잘못된 요청 형식
누락된 인증 헤더
오래된 엔드포인트 사용
실제 응답과 맞지 않는 타입 생성

Apidog MCP 서버는 코딩 에이전트가 팀의 API 사양을 직접 참조하도록 연결할 수 있습니다.

Claude Code: 네이티브 MCP 연결
dsh: dsh-mcp-manager를 통한 연결

또한 Apidog 다운로드 후 두 에이전트가 작업하는 동일한 프로젝트에 MCP 서버를 구성할 수 있습니다.

에이전트가 코드를 수정한 뒤에는 Apidog CLI를 사용해 회귀 테스트를 실행할 수 있습니다. 그러면 어떤 에이전트를 선택하더라도 동일한 API 사양과 테스트 기준을 적용할 수 있습니다.

어떤 도구를 선택해야 할까?

단 하나의 승자를 고르기보다 프로젝트 요구사항에 맞춰 선택하는 편이 정확합니다.

DeepSeek Harness를 선택할 때

다음 조건이라면 dsh를 검토할 만합니다.

소스 코드 검토와 포크가 필요함
MIT 라이선스가 필수임
특정 모델 공급업체에 종속되고 싶지 않음
DeepSeek, OpenAI 호환 모델, 클라우드 카탈로그를 하나의 하네스로 사용하고 싶음
에이전트 루프와 플러그인 커널 자체를 수정하고 싶음
프리뷰 단계의 호환성 변경을 감수할 수 있음

다음 명령으로 바로 시작할 수 있습니다.

npx @deepseek-ai/dsh web

Claude Code를 선택할 때

다음 조건이라면 Claude Code가 더 적합합니다.

바로 사용할 수 있는 안정적인 제품이 필요함
터미널, IDE, 데스크톱, 웹, 모바일을 오가며 작업함
스킬, 훅, 서브 에이전트, 네이티브 MCP가 필요함
세분화된 권한 모드와 관리형 정책이 필요함
CI/CD 통합이 중요함
Claude 모델 사용에 만족함
구독 기반의 예측 가능한 비용을 선호함

두 도구를 함께 사용하는 방법

두 도구를 모두 실행하는 것도 현실적인 선택입니다. dsh는 하네스 자체가 무료이고 다음 명령으로 즉시 실험할 수 있습니다.

npx @deepseek-ai/dsh web

두 도구를 함께 사용할 때는 API 계층을 공통 기준으로 관리하는 것이 중요합니다.

Apidog에서 API 사양을 작성하고 최신 상태로 유지합니다.
MCP를 통해 동일한 사양을 Claude Code 또는 dsh에 제공합니다.
에이전트가 생성하거나 수정한 코드를 저장합니다.
Apidog CLI로 회귀 테스트를 실행합니다.
실패한 테스트 결과를 다시 에이전트에 전달합니다.

이 구조를 사용하면 에이전트의 모델이나 하네스가 바뀌어도 API 계약과 테스트 기준은 유지할 수 있습니다.

자주 묻는 질문

DeepSeek Harness는 Claude Code와 달리 실제로 오픈소스인가요?

네. dsh는 MIT 라이선스를 따르며, 에이전트 루프와 플러그인 커널을 포함한 소스 코드가 GitHub에 공개되어 있습니다.

Claude Code의 공개 리포지토리는 이슈와 문서를 위한 공간입니다. Anthropic의 상업 약관이 적용되며, 포크할 수 있는 에이전트 소스 코드는 제공되지 않습니다.

DeepSeek Harness에서 Claude 모델을 사용할 수 있나요?

네. dsh는 Anthropic, OpenAI, Bedrock, Vertex, Azure 같은 카탈로그 제공자를 지원하며, settings.yaml을 통해 사용자 지정 OpenAI 호환 엔드포인트도 등록할 수 있습니다.

반대로 Claude Code는 Claude 모델만 사용합니다. Anthropic에서 직접 제공하든 Bedrock, Vertex, Foundry를 통해 제공하든 모델은 Claude입니다.

DeepSeek Harness는 일상적인 작업에 충분히 안정적인가요?

dsh는 개발자 프리뷰이며, README에 호환성을 깨뜨리는 변경 사항이 있을 수 있다고 명시되어 있습니다.

실제 작업에 사용할 수는 있지만 설정과 플러그인이 변경될 가능성을 고려해야 합니다. 워크플로우를 자주 수정할 수 없다면 Claude Code가 더 안전한 선택입니다.

두 에이전트 모두 Apidog와 작동하나요?

네. Apidog MCP 서버는 MCP를 지원하는 에이전트에 API 사양을 노출할 수 있습니다.

Claude Code: 네이티브 MCP 사용
dsh: 커뮤니티 dsh-mcp-manager 플러그인 사용

Apidog CLI는 두 에이전트의 터미널 워크플로우에서 스크립트화된 회귀 테스트를 실행하는 데 사용할 수 있습니다. dsh 설정은 DeepSeek Harness에서 Apidog CLI 사용하기에서 자세히 확인할 수 있습니다.

DeepSeek Harness (dsh)란? 오픈소스 Claude 코드 대항마 총정리

Rihpig — Thu, 20 Aug 2026 04:30:58 +0000

DeepSeek은 2026년 8월 13일 모델이 아니라 모델을 실행하는 기계를 출시했습니다. DeepSeek Harness(dsh)는 DeepSeek의 공식 오픈소스 에이전트 하네스로, 대규모 언어 모델(LLM)을 세션 루프, 도구 실행, 권한 확인, 로컬 웹 UI를 갖춘 코딩 에이전트로 연결합니다. DeepSeek V4-Pro가 API에 출시된 날 함께 공개됐으며, VentureBeat는 이를 Claude Code의 오픈소스 경쟁자로 보도했습니다.

지금 Apidog를 사용해 보세요

개발자 커뮤니티는 빠르게 반응했습니다. 8월 20일 기준, 출시 1주일 만에 deepseek-harness 저장소는 약 169,000개의 스타와 18,100개의 포크를 기록했습니다. 이 수치는 코드 자체보다, 개발자가 직접 검사하고 수정하며 여러 모델에 연결할 수 있는 에이전트 하네스를 원한다는 점을 보여줍니다.

DeepSeek Harness는 무엇인가요?

모델은 다음 토큰을 예측합니다. 반면 하네스는 모델이 실제로 작업할 수 있게 만드는 실행 환경입니다.

하네스는 다음을 제어합니다.

모델에 전달할 컨텍스트
호출 가능한 도구(파일 편집, 셸, 검색 등)
파일 쓰기와 명령 실행에 대한 승인 방식
다단계 세션의 상태 유지 및 기록
모델 응답을 도구 실행 결과와 다시 연결하는 에이전트 루프

Claude Code, Codex CLI, Gemini CLI도 각각 벤더 모델 위에서 동작하는 하네스입니다. 개념적 차이가 궁금하다면 Claude Code vs Codex CLI를 참고할 수 있습니다.

DeepSeek Harness의 핵심 특징은 세 가지입니다.

공식 프로젝트입니다. DeepSeek AI가 직접 개발하며, 단순한 커뮤니티 API 래퍼가 아닙니다.
MIT 라이선스 오픈소스입니다. THIRD_PARTY_NOTICES 파일에서 타사 종속성을 확인할 수 있고, 에이전트 루프 구현도 직접 읽고 검토할 수 있습니다.
개발자 미리보기입니다. README는 호환성을 깨는 변경 사항이 있을 수 있다고 명시합니다. 프로덕션 표준 도구로 즉시 채택하기보다, 격리된 프로젝트에서 먼저 검증하는 편이 좋습니다.

dsh는 DeepSeek V4-Pro API 출시와 동시에 공개됐습니다. V4-Pro의 엔드포인트, 모델 ID, 요청 형식은 DeepSeek V4-Pro API 사용 가이드에서 확인할 수 있습니다.

아키텍처: 모든 것이 플러그인입니다

대부분의 코딩 에이전트 하네스는 모놀리식 구조입니다. 에이전트 루프, 모델 클라이언트, 도구 정의, 세션 저장소가 하나의 애플리케이션에 결합됩니다. 설정값을 바꾸거나 일부 확장은 가능하지만, 핵심 구성 요소를 교체하기는 어렵습니다.

dsh는 다른 접근을 택합니다. 설계 원칙은 “모든 것이 플러그인”이며, Cordis 프레임워크를 기반으로 합니다.

실무적으로는 일반적으로 묶여 있는 에이전트 구성 요소를 교체 가능한 모듈로 분리했다는 뜻입니다.

구성 요소	dsh에서의 역할
모델 어댑터	DeepSeek, OpenAI 호환 API 등 LLM 백엔드와 통신
도구 레지스트리	파일 편집, 셸 실행, 검색 등 사용 가능한 도구 등록
세션 로그	세션 기록과 재생 방식 관리
에이전트 루프	결정 → 행동 → 관찰 흐름 제어

이 구조는 다음과 같은 경우에 특히 유용합니다.

모델별로 다른 작업을 할당해야 하는 팀
저장소마다 다른 권한 정책을 적용해야 하는 팀
컨텍스트 압축 또는 세션 관리 방식을 실험하려는 팀
내부 도구를 에이전트 도구로 연결하려는 개발자

예를 들어, “읽기 전용 분석”과 “파일 수정 가능한 구현 작업”에 서로 다른 도구 세트와 권한 정책을 적용하는 플러그인을 만들 수 있습니다.

다만 트레이드오프도 분명합니다. 교체 가능한 부분이 많을수록 깨질 수 있는 표면적도 넓어집니다. 개발자 미리보기 단계에서는 플러그인 API, 설정, 워크플로우가 버전 업데이트로 변경될 수 있으므로 플러그인 버전과 설정을 함께 관리해야 합니다.

빠른 시작: 로컬 에이전트 실행하기

가장 빠른 설치 방법은 다음 명령입니다.

npx @deepseek-ai/dsh web

명령을 실행하면 로컬 웹 UI가 시작됩니다.

http://127.0.0.1:3080

브라우저 자동 열기를 막으려면 --no-open을 추가합니다.

npx @deepseek-ai/dsh web --no-open

전역 설치나 별도 계정 생성은 필수가 아닙니다.

소스에서 실행하기

저장소를 직접 빌드하려면 다음 순서로 실행합니다.

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness

pnpm install
pnpm run build
pnpm dsh web

첫 실행 체크리스트

웹 UI가 열리면 아래 순서로 설정합니다.

DeepSeek API 키를 설정합니다.

자격 증명은 $DSH_HOME/.credentials.yaml에 저장됩니다. 기본 설정 파일에는 키 자체가 아니라 키 참조만 포함됩니다.
작업 공간을 선택합니다.

UI에서 작업 공간을 추가하고 선택합니다. 작업 공간을 선택하기 전에는 세션 컴포저를 사용할 수 없습니다.
작업을 실행하고 권한 요청을 검토합니다.

활성 권한 정책에 따라 파일 쓰기나 셸 명령 실행 전에 승인 프롬프트가 표시됩니다.

처음에는 권한이 제한된 테스트 저장소에서 실행하는 것이 좋습니다. 예를 들어, 실제 서비스 저장소 대신 샘플 프로젝트를 준비해 다음과 같은 작업으로 동작을 확인할 수 있습니다.

현재 프로젝트 구조를 요약해 줘.

그다음 읽기 전용 작업이 기대대로 작동하는지 확인한 후에 파일 변경 작업을 요청합니다.

README에 로컬 실행 방법을 추가해 줘. 변경 전 diff를 먼저 보여 줘.

웹 UI 외 실행 모드

dsh web은 다음 명령의 축약형입니다.

dsh --profile web

프로필은 $DSH_HOME/profiles/ 아래에 위치합니다.

자동화나 CI에서는 헤드리스 프로필을 사용할 수 있습니다.

dsh --profile headless "프로젝트의 테스트 실패 원인을 분석해 줘"

이 모드는 단일 세션을 실행하고 결과를 출력한 뒤 종료하므로 스크립트와 CI 작업에 적합합니다.

구성과 플러그인을 점검할 때는 다음 명령도 유용합니다.

# 현재 구성 트리 출력
dsh --dump-config

# 기본 구성 출력
dsh --dump-default-config

# 프로필 플러그인 관리
dsh plugin

전체 CLI 옵션은 CLI README에서 확인할 수 있습니다.

어떤 모델을 실행할 수 있나요?

DeepSeek 모델이 기본값이며, V4-Pro가 주요 페어링입니다. 에이전트는 반복적으로 모델 호출을 수행하므로 토큰 비용도 고려해야 합니다. DeepSeek의 가격 정책 관련 정보는 DeepSeek V4-Pro 가격 인하와 공식 API 문서에서 확인할 수 있습니다.

하지만 dsh의 모델 어댑터는 플러그인 구조이므로 DeepSeek 모델에만 묶이지 않습니다.

내장 제공업체

카탈로그에서 다음 제공업체 항목을 사용할 수 있습니다.

Anthropic
OpenAI
Amazon Bedrock
Google Vertex AI
Azure

각 제공업체는 자체 자격 증명 처리를 지원합니다.

OpenAI 호환 엔드포인트 추가하기

OpenAI 호환 API라면 $DSH_HOME/settings.yaml에 다음 정보를 등록할 수 있습니다.

기본 URL
API 키를 읽을 환경 변수
사용할 모델 목록

이 방식은 클라우드 API뿐 아니라 로컬 런타임과 내부 게이트웨이에도 적용할 수 있습니다.

모델을 선택하면 이후 새 세션의 기본값으로 사용됩니다. 또한 각 세션은 시작 시 사용한 모델을 기록하므로, 프로젝트 진행 중 모델을 바꿔도 세션 이력을 구분할 수 있습니다.

정확한 설정 형식은 제공업체 가이드를 참고하세요. 사용자 지정 엔드포인트용 YAML 예시는 DeepSeek Harness에서 모든 모델을 실행하는 방법에서 확인할 수 있습니다.

플러그인 생태계: 설치 전 검토가 필수입니다

플러그인은 dsh-plugin GitHub 토픽에서 찾을 수 있습니다. 커뮤니티 논의는 GitHub Discussions와 Discord 서버에서 이뤄집니다.

출시 초기 생태계에서 확인할 수 있는 유형은 다음과 같습니다.

데스크톱 래퍼

deepseek-harness-desktop(Tauri), dsh_desktop(Windows) 같은 프로젝트가 웹 UI를 네이티브 앱 형태로 패키징합니다.
기능 플러그인

dsh-context, dsh-vision-router 등은 세션 컨텍스트나 라우팅 기능을 확장합니다.
MCP 관련 플러그인

작성 시점 기준으로 dsh 코어는 기본 Model Context Protocol(MCP) 지원을 제공하지 않습니다. 대신 커뮤니티 플러그인인 dsh-mcp-manager가 MCP 설정 페이지와 서버 연결 기능을 제공합니다.

MCP 플러그인으로 가능한 작업에는 다음이 포함됩니다.

원격 HTTP MCP 서버 연결
로컬 stdio MCP 서버 연결
OAuth 또는 정적 토큰 인증
mcp____* 이름으로 도구 등록
작업 공간 .dsh 디렉터리의 프로젝트별 서버 설정

여기서 중요한 구분이 있습니다.

“dsh가 MCP를 지원한다”는 표현은 현재 시점에서는 “커뮤니티 플러그인을 통해 MCP를 연결할 수 있다”는 의미입니다.

코어 기능과 커뮤니티 플러그인을 같은 수준의 안정성으로 간주하면 안 됩니다. 특히 API 키나 OAuth 토큰을 처리하는 플러그인은 설치 전에 소스, 유지보수 상태, 권한 범위를 검토하세요.

API 워크플로우에 적용하는 방법

에이전트 하네스는 결국 API 호출을 수행하는 실행 환경입니다. 모델 API를 호출할 뿐 아니라, 에이전트가 작업하는 코드베이스 안의 API 계약도 해석합니다.

문제는 코드베이스의 엔드포인트 정보가 실제 API 동작과 다를 수 있다는 점입니다. 오래된 문서, 누락된 스키마, 변경된 응답 형식이 있으면 에이전트는 잘못된 계약을 기반으로 코드를 작성할 수 있습니다.

따라서 에이전트에게 API 관련 구현을 맡기기 전에 API 표면을 먼저 검증하는 편이 좋습니다.

Apidog를 사용하면 다음 흐름을 구성할 수 있습니다.

OpenAPI 사양을 설계하거나 가져옵니다.
실제 엔드포인트를 사양과 비교해 테스트합니다.
백엔드 변경 중에도 사용할 수 있는 모의 서버를 구성합니다.
검증된 사양과 모의 응답을 기준으로 에이전트 작업을 진행합니다.

이렇게 하면 에이전트가 오래된 코드나 추측에 의존하는 대신, 명시적인 API 계약을 기반으로 구현할 수 있습니다.

MCP를 통해 API 사양 연결하기

Apidog MCP 서버는 MCP를 통해 API 사양을 AI 도구에 노출합니다.

dsh에서는 앞서 언급한 커뮤니티 dsh-mcp-manager 플러그인을 통해 연결할 수 있습니다.

실행 순서는 다음과 같습니다.

dsh-mcp-manager 플러그인을 설치합니다.
Apidog MCP 서버를 등록합니다.
프로젝트별 MCP 구성을 .dsh 디렉터리에 저장합니다.
에이전트가 추측 대신 실제 API 사양을 조회하도록 작업을 요청합니다.
CLI 기반 테스트를 실행해 생성된 구현을 검증합니다.

예를 들어 에이전트에게 다음처럼 요청할 수 있습니다.

등록된 API 사양을 확인한 뒤, POST /users 엔드포인트용 TypeScript 클라이언트를 구현해 줘.
응답 스키마와 오류 코드를 사양 기준으로 처리하고, 테스트 실행 명령도 제안해 줘.

에이전트가 직접 실행할 수 있는 CLI 테스트까지 포함한 흐름은 DeepSeek Harness에서 Apidog CLI 사용하기에서 확인할 수 있습니다. 시작하기 전에 Apidog를 다운로드하고 API 사양을 가져오면 됩니다.

지금 시도해야 할까요?

용도에 따라 판단하는 것이 가장 현실적입니다.

지금 시도하기 좋은 경우

에이전트 하네스의 내부 구조를 직접 이해하고 싶다.
작업별로 서로 다른 모델을 선택해야 한다.
자체 호스팅 모델 또는 OpenAI 호환 엔드포인트를 사용한다.
에이전트용 도구나 플러그인을 직접 만들고 싶다.
이미 DeepSeek API를 사용하고 있으며 V4-Pro 기반 에이전트 경험을 원한다.

기다리는 편이 좋은 경우

안정적인 일상 업무용 도구가 필요하다.
지원 계약과 검증된 배포 경로가 필요하다.
커뮤니티 플러그인이 자격 증명을 처리하는 환경을 허용하기 어렵다.
성숙한 제품 수준의 UX와 호환성을 기대한다.

실무적인 접근은 병행 운영입니다. 프로덕션 작업에는 현재 검증된 에이전트를 유지하고, 사이드 프로젝트나 격리된 샌드박스에서 dsh를 테스트하세요. 기존 도구와의 차이가 궁금하다면 DeepSeek Harness vs Claude Code를 참고할 수 있습니다.

자주 묻는 질문

DeepSeek Harness는 무료인가요?

하네스 자체는 MIT 라이선스 기반의 무료 오픈소스입니다. 다만 연결한 모델 API 사용량은 해당 제공업체의 과금 정책을 따릅니다.

모델 어댑터가 플러그인 구조이므로 로컬 호스팅 모델에 연결할 수도 있습니다. 설정 방법은 DeepSeek Harness에서 모든 모델 실행을 참고하세요.

dsh는 DeepSeek 모델에서만 작동하나요?

아니요. DeepSeek 모델이 기본값이지만, 모델 어댑터는 플러그인입니다. Anthropic, OpenAI, Bedrock, Vertex, Azure를 포함하는 제공업체 항목을 사용할 수 있으며, OpenAI 호환 엔드포인트도 $DSH_HOME/settings.yaml을 통해 추가할 수 있습니다.

DeepSeek Harness를 내 코드베이스에서 실행해도 안전한가요?

권한 정책과 설치한 플러그인에 따라 다릅니다.

웹 UI는 작업 공간 선택을 요구하고, 활성 권한 정책에 따라 파일 쓰기와 셸 명령 전에 승인 요청을 표시합니다. 하지만 개발자 미리보기이며, 데스크톱 래퍼를 포함한 커뮤니티 플러그인은 API 키를 처리할 수 있는 타사 코드입니다.

다음 원칙을 권장합니다.

처음에는 테스트 저장소에서 실행합니다.
설치 전 플러그인 소스와 유지보수 상태를 검토합니다.
API 키와 OAuth 토큰의 저장 위치를 확인합니다.
중요한 브랜치나 복구가 어려운 저장소에서는 직접 실행하지 않습니다.
파일 변경 전 diff 확인을 요청합니다.

하네스는 모델과 어떻게 다른가요?

모델은 추론 엔진이고, 하네스는 모델이 실제로 행동하게 만드는 실행 계층입니다.

하네스는 세션 관리, 도구 호출, 파일 접근, 권한 프롬프트, 컨텍스트 조립을 담당합니다. 따라서 같은 모델을 사용해도 하네스의 도구 구성, 권한 정책, 컨텍스트 전략이 다르면 에이전트의 동작 결과도 크게 달라질 수 있습니다.

GLM-5.3 API 사용법

Rihpig — Sun, 16 Aug 2026 15:36:19 +0000

국제적으로 Z.ai로 활동하는 중국 연구소 Zhipu AI는 2026년 8월 14일 GLM-5.3을 출시했습니다. Zhipu의 내부 평가에 따르면 GLM-5.2 대비 코딩 성능은 50% 향상됐고, Terminal-Bench 3.0 점수는 4.6에서 28.3으로 상승했습니다. BigGo의 출시 보고서에 따르면 Zhipu는 코딩 및 에이전트 기능이 “Claude Fable 5에 근접한다”고 설명합니다. 오픈 웨이트는 약 2주 후 공개될 예정입니다. 전체 기능 분석과 벤치마크 표는 GLM-5.3이란 무엇인가를 참고하십시오. 이 글에서는 GLM-5.3 API를 실제 애플리케이션에 연결하는 빠른 시작 과정을 다룹니다.

지금 Apidog 사용해 보기

이 글에서는 API 키 발급, cURL 첫 호출, OpenAI SDK를 사용한 Python·Node.js 구현, 스트리밍, 주요 매개변수 조정, 그리고 애플리케이션 코드 작성 전에 Apidog에서 요청을 검증하는 방법을 다룹니다. Z.ai API는 OpenAI 호환 형식을 사용하므로, 기존 OpenAI 스타일 엔드포인트를 호출해 본 경험이 있다면 호스트와 모델 ID만 바꾸면 대부분의 코드를 재사용할 수 있습니다.

주의: GLM-5.3은 출시 직후 문서가 빠르게 갱신될 수 있습니다. 아래에서 문서로 확인된 정보와 GLM-5 제품군의 기존 명명 규칙을 기반으로 한 예상 정보를 구분해 설명합니다. 프로덕션에 하드코딩하기 전에는 항상 공식 문서를 다시 확인하십시오.

요약 (TL;DR)

GLM-5.3은 2026년 8월 14일 출시되었습니다. Zhipu 내부 평가에서 GLM-5.2 대비 코딩 성능이 50% 향상됐으며, Terminal-Bench 3.0 점수는 4.6에서 28.3으로 상승했습니다. Terminal-Bench 3.0 및 Agents’ Last Exam에서 오픈소스 모델 중 1위를 차지했다고 발표했습니다.
API는 OpenAI 호환입니다. 국제 엔드포인트는 POST https://api.z.ai/api/paas/v4/chat/completions이며, Authorization: Bearer $GLM_API_KEY 헤더를 사용합니다. 중국 본토 엔드포인트는 https://open.bigmodel.cn/api/paas/v4/chat/completions입니다.
작성 시점의 GLM-5 문서에는 모델 ID로 glm-5가 표시되어 있었습니다. 가격 페이지에는 glm-5.2, glm-5.1이 별도 모델로 등록되어 있으므로 glm-5.3도 같은 점 표기 규칙을 따를 것으로 예상되지만, 사용 전 확인이 필요합니다.
출시 시점에 Zhipu는 5.3 전용 API 가격을 공개하지 않았습니다. 공식 가격 페이지에는 참고값으로 GLM-5.2가 입력 100만 토큰당 $1.40, 출력 100만 토큰당 $4.40, GLM-5가 각각 $1.00 및 $3.20으로 표시되어 있었습니다.
오픈 웨이트는 2026년 8월 28일경 Hugging Face에 공개될 예정입니다.
먼저 Apidog에서 지역별 환경과 모델 변수를 구성하고, 프롬프트·스트리밍·추론 모드를 검증한 뒤 애플리케이션 코드로 옮기십시오.

GLM-5.3이 중요한 이유

기본 모델 아키텍처는 GLM-5 제품군과 동일합니다. 이번 릴리스의 향상은 GLM-5에 대한 확장된 후처리 학습에서 비롯됐다고 설명됩니다. Zhipu가 공개한 수치에 따르면 Terminal-Bench 3.0은 4.6에서 28.3으로 상승했으며, SWE-Marathon 점수도 GLM-5.2 대비 약 두 배 증가했습니다.

보안 평가에서는 CyberGym 84.5%를 기록해 Claude Mythos 5 및 GPT-5.6 Sol보다 약간 높았다고 발표했지만, ExploitBench는 54.4%로 최첨단 모델보다 낮았습니다. 50% 코딩 성능 향상 및 일부 벤치마크 점수는 Zhipu 자체 평가에서 나온 수치이므로, 독립적인 재현 결과가 나오기 전까지는 공급업체 발표로 해석해야 합니다.

Z.ai의 문서에 따르면 GLM-5 제품군은 총 7,440억 개 매개변수의 MoE(Mixture of Experts) 구조입니다. 순방향 통과마다 약 400억 개 매개변수가 활성화되며, 컨텍스트 창은 20만 토큰입니다. 이는 GLM-5 제품군 사양이며, 5.3에만 한정된 주장은 아닙니다.

API 사용 관점에서 확인할 핵심은 두 가지입니다.

Pandaily의 출시 보도에 따르면 Zhipu는 출시 약 2주 후인 8월 28일경 오픈 웨이트와 위험 검토 시스템을 공개할 예정입니다. 자체 호스팅을 계획한다면 지금의 API 응답을 회귀 기준선으로 저장해 두십시오. 관련 전략은 GLM-5.3 자체 호스팅 준비 가이드에서 확인할 수 있습니다.
Seeking Alpha는 Zhipu를 “중국 OpenAI 경쟁자”로 평가합니다. 이 수준의 기능을 가진 오픈 웨이트가 공개되면 모델 선택과 비용 구조에 영향을 줄 수 있습니다.

API 키 받기

플랫폼은 지역에 따라 나뉩니다. 엔드포인트, 청구, 지연 시간 및 규정 준수 요구사항이 달라질 수 있으므로 먼저 사용할 플랫폼을 정하십시오.

Z.ai: 국제 사용자

Z.ai에서 계정을 만들고 API 콘솔에서 키를 생성합니다.

가입: z.ai
문서: docs.z.ai
기본 엔드포인트: https://api.z.ai/api/paas/v4

중국 본토 외 지역에서 사용하는 기본 경로입니다.

Bigmodel.cn: 중국 본토 사용자

중국 본토에서는 open.bigmodel.cn을 사용합니다.

기본 엔드포인트: https://open.bigmodel.cn/api/paas/v4
인증 및 요청 형식: 국제 API와 동일
청구 체계: 국제 플랫폼과 별도

키는 코드에 직접 넣지 말고 환경 변수로 주입하십시오.

export GLM_API_KEY="your-key-from-the-console"

종량제 API가 아니라 GLM 코딩 플랜을 사용 중이라면, 8월 14일에 모든 사용자의 할당량이 재설정됐다는 점도 확인하십시오.

엔드포인트 및 인증

작성 시점의 GLM-5 문서 기준 국제 채팅 완성 엔드포인트는 다음과 같습니다.

POST https://api.z.ai/api/paas/v4/chat/completions

중국 본토에서는 호스트만 변경합니다.

POST https://open.bigmodel.cn/api/paas/v4/chat/completions

인증은 Bearer 토큰 헤더 하나로 처리합니다.

Authorization: Bearer $GLM_API_KEY

요청 및 응답은 OpenAI 채팅 완성 형식과 호환됩니다.

요청: model, messages
응답: choices, message, finish_reason, usage
스트리밍: stream: true

즉, 공식 OpenAI SDK를 그대로 사용하면서 base_url만 Z.ai API 주소로 바꾸면 됩니다. 다른 OpenAI 호환 공급업체용 코드를 작성한 적이 있다면 호스트와 모델만 교체해 포팅할 수 있습니다. 이 접근 방식은 DeepSeek V4 Pro API 사용법과 동일합니다.

모델 ID 확인하기

출시 당일 문서에는 모델 문자열로 glm-5가 표시되어 있었고, 5.3 전용 표기가 아직 반영되지 않았습니다. 가격 페이지에 glm-5.2, glm-5.1이 별도 모델로 표기된 점을 고려하면 새 ID는 glm-5.3일 가능성이 높습니다.

아래 예제에서는 glm-5.3을 사용합니다. 단, 프로덕션 반영 전에는 반드시 공식 모델 문서에서 현재 ID를 확인하십시오. 해당 지역에서 glm-5.3이 404를 반환하면 같은 제품군의 glm-5를 사용해야 할 수 있습니다.

cURL로 첫 요청 보내기

먼저 최소 요청으로 인증, 엔드포인트, 모델 ID가 모두 올바른지 확인합니다.

curl "https://api.z.ai/api/paas/v4/chat/completions" \
  -H "Authorization: Bearer $GLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.3",
    "messages": [
      {
        "role": "system",
        "content": "You are a code reviewer. Flag issues as blocking or non-blocking."
      },
      {
        "role": "user",
        "content": "Review this shell script for safety:\n\nrm -rf $BUILD_DIR/*\ncp dist/* $DEPLOY_TARGET"
      }
    ],
    "temperature": 0.3,
    "max_tokens": 1024
  }'

성공 응답에서는 다음 필드를 우선 확인하십시오.

choices[0].message.content
usage.prompt_tokens
usage.completion_tokens
finish_reason

셸과 터미널 관련 검토 프롬프트는 Terminal-Bench 성능 향상을 빠르게 점검하기 위한 적절한 스모크 테스트입니다.

다단계 코딩 작업이나 에이전트 작업에는 thinking 매개변수를 활성화할 수 있습니다.

"thinking": { "type": "enabled" }

짧은 추출, 분류, 단순 변환 요청에서는 추론 토큰이 불필요할 수 있으므로 비활성화한 결과와 비교하십시오.

Python 빠른 시작

OpenAI Python SDK를 설치합니다.

pip install --upgrade openai

그다음 base_url을 Z.ai API 경로로 지정합니다.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["GLM_API_KEY"],
    base_url="https://api.z.ai/api/paas/v4",
)

response = client.chat.completions.create(
    model="glm-5.3",
    messages=[
        {
            "role": "system",
            "content": "You are a code reviewer. Flag issues as blocking or non-blocking.",
        },
        {
            "role": "user",
            "content": (
                "Review this Flask route for security issues:\n\n"
                "@app.route('/user/<id>')\n"
                "def get_user(id):\n"
                "    return db.execute(f'SELECT * FROM users WHERE id = {id}')"
            ),
        },
    ],
    temperature=0.3,
    max_tokens=2048,
)

print(response.choices[0].message.content)
print("input tokens:", response.usage.prompt_tokens)
print("output tokens:", response.usage.completion_tokens)

첫날부터 usage를 로그에 기록하십시오. 5.3 전용 가격이 공개되지 않은 상태에서는 실제 입력·출력 토큰 사용량이 비용을 추정할 수 있는 가장 신뢰할 만한 운영 지표입니다.

Node.js 빠른 시작

Node.js에서도 openai 패키지를 사용합니다.

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.GLM_API_KEY,
  baseURL: "https://api.z.ai/api/paas/v4",
});

const response = await client.chat.completions.create({
  model: "glm-5.3",
  messages: [
    {
      role: "system",
      content:
        "You are a terminal automation agent. Return each step as a shell command with a one-line rationale.",
    },
    {
      role: "user",
      content:
        "A Node service on port 3000 stopped responding after a deploy. Give me a diagnosis sequence.",
    },
  ],
  temperature: 0.3,
  max_tokens: 2048,
});

console.log(response.choices[0].message.content);

기존 코드베이스가 이미 OpenAI API를 호출한다면 별도 추상화 계층을 새로 만들 필요는 없습니다. Z.ai baseURL을 사용하는 두 번째 OpenAI 인스턴스를 만들고 작업별로 요청을 라우팅하십시오. 그러면 GLM-5.3과 기존 모델의 A/B 비교가 코드 재작성 대신 라우팅 설정 문제로 바뀝니다.

스트리밍

문서는 표준 stream 플래그 기반 스트리밍을 지원합니다. Python 예제는 다음과 같습니다.

stream = client.chat.completions.create(
    model="glm-5.3",
    messages=[
        {
            "role": "user",
            "content": "Explain the N+1 query problem with a concrete ORM example.",
        }
    ],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

원시 HTTP 요청에서는 본문에 다음 값을 추가하고 SSE(Server-Sent Events)를 파싱합니다.

"stream": true

실무에서는 다음 두 가지를 고려하십시오.

토큰 사용량은 마지막 청크와 함께 또는 스트림 종료 뒤에 도착할 수 있습니다. 정확한 비용 계산은 스트림을 완전히 닫은 뒤 수행하십시오.
thinking을 활성화하면 어려운 프롬프트에서 첫 토큰이 도착하기까지 더 긴 대기 시간이 발생할 수 있습니다. 모델이 응답 전 추론 토큰을 사용하기 때문입니다.

중요한 매개변수

매개변수	유형	구현 시 사용 기준
`max_tokens`	정수	출력 길이 상한입니다. 비용 제어를 위해 항상 지정하십시오.
`temperature`	숫자	코드·추출 작업에는 `0.2~0.4`, 개방형 작성에는 `0.7+`를 사용하십시오.
`thinking`	객체	`{"type": "enabled"}`로 다단계 작업의 추론 모드를 켭니다.
`stream`	불리언	단일 JSON 응답 대신 SSE 청크를 받습니다.
`messages`	배열	표준 OpenAI 역할인 `system`, `user`, `assistant`를 사용합니다.

비용은 공식 가격 페이지를 기준으로 확인하십시오. 출시 당시 5.3 전용 가격은 공개되지 않았으므로 리셀러나 비공식 페이지의 토큰 가격 추정치는 신뢰하지 않는 것이 좋습니다.

작성 시점의 참고 가격은 다음과 같습니다.

모델	입력 100만 토큰	출력 100만 토큰
GLM-5.2	$1.40	$4.40
GLM-5	$1.00	$3.20

유료 GLM 모델의 캐시된 입력은 80~85% 할인될 수 있으므로, 반복되는 시스템 프롬프트와 공통 컨텍스트는 가능한 한 안정적인 접두사로 구성해 캐시 적중을 유도하십시오. 비용 관리 패턴은 DeepSeek 가격 인상 사후 분석도 참고할 수 있습니다.

애플리케이션 코드 작성 전에 Apidog에서 GLM-5.3 테스트하기

스크립트에서 프롬프트를 반복 수정하며 호출하면 편집·실행·로그 탐색 과정마다 토큰 비용이 발생합니다. Z.ai API는 OpenAI 호환이므로, API 클라이언트에서 요청 형식을 먼저 고정한 뒤 코드로 옮기는 편이 효율적입니다.

Apidog에서는 다음 순서로 구성하십시오.

프로젝트를 만들고 채팅 완성 요청을 추가합니다.

OpenAI 호환 사양을 가져오거나 POST /chat/completions를 직접 정의합니다. 요청 본문에는 model과 messages를 포함합니다.
지역별 환경을 만듭니다.

zai-international과 bigmodel-mainland 환경을 생성합니다.

   zai-international
   BASE_URL=https://api.z.ai/api/paas/v4

   bigmodel-mainland
   BASE_URL=https://open.bigmodel.cn/api/paas/v4

인증 헤더는 환경 변수로 관리합니다.

   Authorization: Bearer {{GLM_API_KEY}}

이렇게 하면 저장된 요청에 API 키를 넣지 않고도 드롭다운에서 지역을 전환할 수 있습니다.

모델 ID를 변수로 분리합니다.

   GLM_MODEL=glm-5.3

출시 주간에는 모델 ID가 변경되거나 glm-5.2와 비교해야 할 수 있습니다. 변수로 분리하면 저장된 모든 요청을 수정하지 않고 한 곳에서 모델을 교체할 수 있습니다.

thinking 활성화 여부를 같은 프롬프트에서 비교합니다. 요청을 복제한 뒤 한쪽에만 다음을 추가합니다.

   "thinking": { "type": "enabled" }

지연 시간, 출력 품질, usage를 비교해 어떤 작업에 추론 토큰을 사용할지 결정하십시오.

스트리밍 요청을 별도로 검증합니다.

SSE 청크가 실시간으로 표시되는지 확인하고, 사용자가 체감할 첫 토큰 응답 시간을 측정하십시오.
좋은 응답을 예시 또는 픽스처로 저장합니다.

이후 UI·파서·후처리 로직을 개발할 때는 라이브 API 호출 대신 저장된 응답을 사용하십시오. 이는 개발 중 토큰 소비를 줄이는 가장 효과적인 방법 중 하나입니다.

저장된 요청에 finish_reason, 응답 스키마, 토큰 수에 대한 검증을 추가하면 스모크 테스트를 회귀 테스트 스위트로 확장할 수 있습니다. API 전반에 적용할 수 있는 워크플로는 QA 엔지니어를 위한 API 테스팅 가이드에서 확인할 수 있습니다.

오류 처리 및 속도 제한

OpenAI 스타일 오류 객체를 예상하십시오.

{
  "error": {
    "message": "...",
    "type": "...",
    "code": "..."
  }
}

일반적으로 처리해야 할 상태 코드는 다음과 같습니다.

상태 코드	일반적인 원인	처리 방법
`400`	잘못된 요청 본문, 알 수 없는 모델 ID	요청 스키마와 모델 변수를 확인합니다.
`401`	누락되었거나 취소된 API 키	환경 변수와 인증 헤더를 확인합니다.
`429`	속도 제한	지터가 포함된 지수 백오프로 재시도합니다.
`5xx`	일시적 서버 오류	재시도 후 실패를 기록합니다.

출시 초기 API를 운영할 때는 다음 습관을 적용하십시오.

429와 5xx에 재시도 정책을 적용합니다. 새 모델 출시 직후에는 트래픽이 집중될 수 있으므로 지터가 포함된 지수 백오프를 사용하십시오.
속도 제한 수치를 추정하지 않습니다. 동시성 및 티어별 제한은 공식 문서에서 현재 값을 확인하십시오.
모델 ID는 구성으로 관리합니다. 5.3의 동작 변화로 프롬프트 품질이 저하되면, glm-5.2로의 롤백은 코드 배포가 아니라 설정 변경으로 끝나야 합니다.

OpenAI 호환 인터페이스이므로 Grok API 테스트 및 디버깅 워크플로도 유사하게 적용할 수 있습니다.

자주 묻는 질문 (FAQ)

GLM-5.3 API의 모델 ID는 무엇인가요?

Zhipu의 기존 명명 규칙을 따르면 glm-5.3이 예상됩니다. 가격 페이지에는 glm-5.2, glm-5.1이 별도 모델로 표시되어 있습니다. 다만 작성 시점의 모델 문서에는 glm-5가 표시되어 있었으므로, 프로덕션 적용 전 docs.z.ai에서 확인하십시오.

모델 ID는 코드에 하드코딩하지 말고 구성 파일이나 환경 변수에 저장하십시오.

GLM-5.3 API는 OpenAI SDK와 호환되나요?

네. base_url을 https://api.z.ai/api/paas/v4로 설정하고 Z.ai API 키를 전달하면 Python 및 Node.js용 공식 openai 패키지를 사용할 수 있습니다. 중국 본토에서는 Bigmodel.cn 엔드포인트를 사용하면 됩니다.

요청·응답 형식과 스트리밍 방식은 OpenAI 채팅 완성 인터페이스와 호환됩니다.

GLM-5.3 API 비용은 얼마인가요?

Zhipu는 2026년 8월 14일 출시 당시 GLM-5.3 전용 가격을 공개하지 않았습니다. 공식 가격 페이지에는 GLM-5.2가 입력 100만 토큰당 $1.40, 출력 100만 토큰당 $4.40으로 표시되어 있습니다.

5.3 가격 항목이 업데이트되기 전까지는 이를 참고값으로 사용하되, 리셀러의 가격 추측은 피하십시오.

GLM-5.3은 Claude 및 GPT와 어떻게 비교되나요?

Zhipu 자체 평가에 따르면 코딩 및 에이전트 기능은 “Claude Fable 5에 근접”합니다. CyberGym은 84.5%로 Claude Mythos 5 및 GPT-5.6 Sol보다 약간 높았다고 발표됐지만, ExploitBench는 54.4%로 최첨단 모델보다 낮았습니다.

이 수치는 독립적으로 재현되기 전까지 공급업체 주장으로 간주해야 합니다. 모델 비교 방법은 Grok 4.6 vs GPT-5.6 vs Claude Fable 5 비교를 참고하십시오.

GLM-5.3을 API 대신 로컬에서 실행할 수 있나요?

아직은 아닙니다. Zhipu는 출시 약 2주 후인 2026년 8월 28일경 Hugging Face 조직에 오픈 웨이트를 공개할 예정이라고 밝혔습니다.

7,440억 매개변수 MoE 설계는 로컬 노트북보다는 서버급 환경을 전제로 합니다. 현재는 호스팅 API를 사용해 프롬프트, 출력 품질, 지연 시간, 토큰 사용량 기준선을 먼저 구축하는 것이 현실적입니다.

GLM-5.3을 스택에 도입하는 순서

에이전트 루프나 코딩 워크로드를 운영한다면 GLM-5.3은 직접 평가할 가치가 있습니다. Terminal-Bench 및 SWE-Marathon 향상은 공급업체 보고서에 기반하지만, 공개된 변화 폭은 실제 워크로드에서 검증해 볼 이유가 됩니다. 오픈 웨이트 공개가 예정되어 있으므로, 지금 저장한 API 요청과 응답은 이후 자체 호스팅 환경의 회귀 기준선으로도 사용할 수 있습니다.

권장 순서는 다음과 같습니다.

API 키를 발급합니다.
cURL 요청으로 인증과 모델 ID를 확인합니다.
Apidog를 다운로드해 국제·중국 본토 환경을 구성합니다.
모델 ID를 변수로 관리합니다.
실제 프롬프트로 thinking 활성화·비활성화 결과를 비교합니다.
응답 스키마, finish_reason, 토큰 사용량을 검증합니다.
검증된 요청만 Python 또는 Node.js 코드로 옮깁니다.

OpenAI 호환 형식 덕분에 애플리케이션 포팅 자체는 어렵지 않습니다. 핵심은 먼저 요청 형식과 운영 기준을 고정하고, 모델 ID·지역 엔드포인트·추론 모드·비용을 구성으로 관리하는 것입니다.

GLM-5.3이란? 지푸(Zhipu)의 오픈 웨이트 코딩 모델 완벽 분석

Rihpig — Sun, 16 Aug 2026 15:32:35 +0000

GLM-5.3은 Zhipu AI가 2026년 8월 14일에 출시한 대규모 언어 모델입니다. Zhipu AI는 국제적으로 Z.ai로 운영되는 중국 연구소이며, GLM-5.3은 GLM-5 기본 모델을 확장된 후처리(post-training)로 개선한 버전입니다. 코딩과 에이전트 작업에 초점을 맞추며, Zhipu는 출시 약 2주 후 Hugging Face에 오픈 웨이트를 공개할 계획입니다. Zhipu 내부 평가에서는 GLM-5.2 대비 코딩 능력이 50% 향상됐다고 주장합니다.

지금 Apidog 사용해 보기

이 출시가 주목받는 이유는 코딩 에이전트 성능과 오픈 웨이트 계획이 결합됐기 때문입니다. Seeking Alpha가 “중국판 OpenAI 경쟁자”라고 묘사한 연구소가 “Claude Fable 5에 근접한다”고 주장하는 코딩 모델을 내놓고, 가중치까지 공개할 예정입니다. DeepSeek의 최신 모델 출시 다음 날 등장했다는 점도 눈여겨볼 만합니다. DeepSeek의 최신 출시는 DeepSeek V4 Pro API 가이드에서 다뤘습니다.

이 글에서는 GLM-5.3의 핵심 사양, 벤치마크 수치의 출처, 오픈 웨이트 공개 계획, API로 첫 요청을 보내는 방법을 정리합니다. Apidog를 사용하면 코드를 작성하지 않고도 요청을 테스트하고 응답을 비교할 수 있습니다.

요약 (TL;DR)

GLM-5.3은 2026년 8월 14일 Zhipu AI(Z.ai)에서 출시됐습니다. GLM-5 기본 모델은 동일하며, 개선 사항은 확장된 후처리에서 비롯됐습니다.
Terminal-Bench 3.0 점수는 4.6에서 28.3으로 상승했습니다. Zhipu는 이를 오픈소스 모델 중 1위라고 보고했습니다.
Agents’ Last Exam에서도 오픈 모델 중 1위를 기록했다고 발표했습니다.
CyberGym 점수는 84.5%이며, Claude Mythos 5 및 GPT-5.6 Sol보다 약간 높다고 보고됐습니다.
ExploitBench 점수는 54.4%로, 최신 비공개 모델에는 여전히 뒤처진다고 설명됩니다.
오픈 웨이트는 2026년 8월 28일경 Hugging Face에 공개될 예정입니다.
GLM-5 계열은 Mixture of Experts(MoE) 아키텍처이며, 총 744B 매개변수, 포워드 패스당 약 40B 활성 매개변수, 200K 컨텍스트 윈도우를 제공합니다.
API는 https://api.z.ai/api/paas/v4/chat/completions에서 OpenAI 호환 형식으로 호출할 수 있습니다.

GLM-5.3은 무엇인가요?

GLM-5.3은 GLM-5 계열의 세 번째 포인트 릴리스이자 코딩 및 에이전트 작업에 집중한 모델입니다. Zhipu는 기본 모델을 재훈련하지 않았습니다. 공식 문서에 따르면 GLM-5 기본 모델은 다음 사양을 유지합니다.

아키텍처: Mixture of Experts
총 매개변수: 744B
포워드 패스당 활성 매개변수: 약 40B
컨텍스트 윈도우: 200K 토큰

즉, GLM-5.3의 변화는 기본 가중치가 아니라 그 위에 적용된 확장된 후처리 파이프라인에 있습니다.

개발자가 여기서 확인해야 할 핵심은 일반적인 채팅 품질이 아니라 실제 에이전트 작업 성능입니다. Zhipu가 강조한 대상 작업은 다음과 같습니다.

터미널 기반 에이전트 작업
장기 소프트웨어 엔지니어링
보안 분석
여러 단계의 명령 실행 및 오류 복구

따라서 GLM-5.3은 다음 조건에 해당한다면 우선 평가할 만합니다.

코딩 에이전트 또는 터미널 자동화를 운영한다.
리포지토리 단위의 긴 작업을 처리해야 한다.
오픈 웨이트 공개 후 자체 하드웨어 실행 가능성도 검토하고 있다.
호스팅 API와 자체 배포 모델을 같은 프롬프트 세트로 비교하려고 한다.

GLM-5.3 벤치마크: 수치와 출처

BigGo Finance 및 Pandaily의 출시 보도에 따르면 다음 결과가 보고됐습니다.

중요한 점은 모든 수치의 증거 수준이 같지 않다는 것입니다. 일부는 공개 리더보드 결과이고, 일부는 Zhipu 내부 평가입니다. 모델 도입 결정을 내릴 때는 이를 구분해야 합니다.

벤치마크	GLM-5.3 결과	맥락	출처
Terminal-Bench 3.0	28.3, 이전 4.6	6.2배 상승, 오픈소스 모델 중 1위	출시 보고서
Agents’ Last Exam	오픈소스 모델 중 1위	출시 시점 점수 미공개	출시 보고서
CyberGym	84.5%	Claude Mythos 5 및 GPT-5.6 Sol보다 약간 높음	출시 보고서
ExploitBench	54.4%	최신 모델에 뒤처짐	출시 보고서
SWE-Marathon	GLM-5.2 대비 약 2배	장기 소프트웨어 엔지니어링	Zhipu 내부
코딩 능력 종합	GLM-5.2 대비 +50%	Zhipu의 주요 주장	Zhipu 내부

벤치마크를 해석하는 방법

Terminal-Bench 3.0의 4.6에서 28.3으로의 상승은 단순한 미세 개선으로 보기 어렵습니다. 이 유형의 벤치마크는 모델이 다음 작업을 수행할 수 있는지 평가합니다.

셸 명령어를 여러 단계로 연결하기
명령 출력 읽기
실패한 작업에서 오류 원인 찾기
수정 후 재실행하기
장기 작업 흐름 유지하기

터미널 에이전트를 구축 중이라면 공개 벤치마크만 보지 말고, 실제 작업을 기준으로 검증해야 합니다. 예를 들어 다음과 같은 프롬프트 세트를 준비할 수 있습니다.

1. 테스트 실패 로그를 분석하고 최소 수정안을 제안한다.
2. monorepo에서 특정 패키지의 의존성 충돌을 찾는다.
3. CI 실패 원인을 진단하고 재현 명령어를 만든다.
4. .git 디렉터리를 제외한 대용량 파일을 찾는다.
5. 보안 설정 오류를 탐지하고 수정 diff를 제안한다.

반면, 코딩 능력 +50%와 SWE-Marathon 약 2배는 Zhipu 내부 수치입니다. 이 수치를 유용한 신호로 활용할 수는 있지만, 독립 평가가 나오기 전까지는 검증된 사실로 취급하지 않는 것이 좋습니다.

“Claude Fable 5에 근접한다”는 것이 실제로 의미하는 바

Zhipu는 GLM-5.3의 코딩 및 에이전트 능력이 “Claude Fable 5에 근접한다”고 설명합니다. 이 표현은 작업 유형별로 나눠서 해석해야 합니다.

경쟁력이 보고된 영역

Terminal-Bench 3.0에서 오픈 모델 중 1위
Agents’ Last Exam에서 오픈 모델 중 1위
CyberGym에서 84.5%

이 수치는 터미널 작업, 에이전트 루프, 자동화된 코딩 워크플로에서 GLM-5.3이 강력한 후보일 수 있음을 시사합니다.

아직 격차가 있는 영역

ExploitBench에서는 54.4%를 기록했으며, 최신 모델에는 뒤처진다고 보고됐습니다. 익스플로잇 개발과 같이 모호한 조건에서 깊은 다단계 추론이 필요한 작업에서는 비공개 최첨단 모델이 여전히 우위를 유지할 수 있습니다.

실무적으로는 다음처럼 접근하세요.

터미널 자동화와 CI 에이전트에는 GLM-5.3을 후보로 추가합니다.
보안 분석이나 익스플로잇 관련 워크로드는 별도 평가 세트를 만듭니다.
비공개 최첨단 모델과 같은 입력, 같은 도구, 같은 시간 제한으로 비교합니다.
단일 점수보다 성공률, 재시도 횟수, 토큰 사용량, 완료 시간까지 기록합니다.

최첨단 모델의 차이를 더 비교하려면 Grok 4.6 vs GPT-5.6 vs Claude Fable 5 비교도 참고할 수 있습니다.

오픈 웨이트 계획: Hugging Face에서 8월 28일경 공개

Zhipu는 GLM-5.3 출시 약 2주 후 오픈 웨이트를 공개하겠다고 밝혔습니다. 예정 시점은 2026년 8월 28일경이며, 이전 오픈 릴리스가 있는 zai-org Hugging Face 조직에 공개될 예정입니다.

2주 간격은 위험 검토 기간으로 설명됩니다. Zhipu는 이번 출시를 위해 현재까지 가장 광범위한 위험 검토 시스템을 구축했다고 밝혔습니다. 특히 CyberGym에서 84.5%를 기록한 모델은 의미 있는 공격적 보안 역량을 가질 수 있으므로, API 제공과 가중치 공개는 서로 다른 수준의 운영 결정을 요구합니다.

자체 호스팅을 준비하는 방법

744B 매개변수 MoE 모델은 포워드 패스당 약 40B만 활성화되더라도 풀 정밀도 추론에 서버급 하드웨어가 필요합니다. 대부분의 팀은 양자화된 커뮤니티 변형이 나온 후 평가하게 될 가능성이 큽니다.

가중치 공개 전에 다음 항목을 준비하세요.

호스팅 API 기준선 확보

지금 API로 실제 프롬프트와 응답을 저장합니다.
평가 데이터셋 작성

실제 이슈, 테스트 실패, 코드 리뷰, CI 오류를 익명화해 사용합니다.
측정 기준 정의

성공률뿐 아니라 지연 시간, 비용, 재시도 횟수, 사람이 수정한 비율을 기록합니다.
서빙 스택 선정

모델 공개 후 사용할 추론 서버와 양자화 방식의 호환성을 확인합니다.
하드웨어 예산 산정

자체 호스팅 비용과 호스팅 API 비용을 같은 토큰 사용량 기준으로 비교합니다.

자체 배포 준비에 대한 자세한 내용은 GLM-5.3 자체 호스팅 가이드를 참고하세요.

GLM-5.3이 오픈 모델 생태계에 어떻게 들어맞는가

가장 직접적인 비교 대상은 DeepSeek입니다. 두 연구소는 모두 중국 기반이며, 오픈 웨이트를 출시하고 공격적인 가격 전략을 사용합니다. 다만 제품 초점에는 차이가 있습니다.

DeepSeek V4 Pro: 범용 플래그십에 가까운 포지셔닝
GLM-5.3: 코딩 에이전트와 터미널 작업에 집중한 포지셔닝

트래픽이 주로 에이전트 코딩에 집중된다면 GLM-5.3을 먼저 평가할 이유가 있습니다.

가격도 고려해야 합니다. DeepSeek API 비용 최적화 가이드에서 다룬 것처럼 오픈 모델 API 가격은 빠르게 변할 수 있습니다. 이는 자체 호스팅을 위험 회피 수단으로 검토하는 팀이 늘어나는 이유이기도 합니다.

Zhipu는 출시 시점에 GLM-5.3 전용 API 가격을 공개하지 않았습니다. 참고로 공식 가격 페이지에는 GLM-5.2가 입력 토큰 1M당 1.4달러, 출력 토큰 1M당 4.4달러로 표시되어 있었습니다. 실제 예산을 확정하기 전에는 반드시 최신 가격을 확인하세요.

양자화 변형이 등장하면 GLM-5.3은 API 의존성 없이 실행 가능한 모델 풀에 합류하게 됩니다. 현재 로컬 모델 환경은 2026년 최고의 로컬 LLM에서 확인할 수 있습니다.

GLM 코딩 플랜 할당량 재설정

기존 사용자에게는 출시일 관련 세부 사항도 있습니다. Zhipu는 8월 14일 모든 사용자의 GLM 코딩 플랜 할당량을 재설정했습니다.

Z.ai에서 코딩 플랜을 구독한 경우, 출시일에 할당량이 새로 시작됐습니다. 이는 GLM-5.3을 테스트할 수 있도록 제공된 기회로 볼 수 있습니다.

다만 코딩 플랜과 API 과금은 구분해야 합니다.

코딩 플랜: Zhipu 코딩 도구용 정액제
API 액세스: 토큰당 과금 방식
할당량 재설정: 코딩 플랜에만 적용
API 비용: 별도 가격 정책 적용

중국 본토 사용자는 open.bigmodel.cn을 통해 별도 플랜 및 요금 체계로 같은 생태계에 접근할 수 있습니다.

5분 안에 API 사용해보기

Z.ai의 API는 OpenAI와 호환되는 형식을 사용합니다.

구분	엔드포인트
국제 엔드포인트	`https://api.z.ai/api/paas/v4/chat/completions`
중국 본토 엔드포인트	`https://open.bigmodel.cn/api/paas/v4/chat/completions`

인증은 Bearer 토큰 방식입니다.

출시 시점의 공식 문서에는 glm-5가 문서화된 모델 ID로 표시되어 있었습니다. 아래 glm-5.3은 GLM-5 계열 명명 규칙을 따른 예시이므로, 배포 전에는 모델 문서 페이지에서 실제 모델 ID를 확인하세요.

cURL 요청 보내기

export GLM_API_KEY="your-key-from-z.ai"

curl https://api.z.ai/api/paas/v4/chat/completions \
  -H "Authorization: Bearer $GLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5.3",
    "messages": [
      {
        "role": "user",
        "content": "Write a bash script that finds the five largest files in a git repo, excluding the .git directory."
      }
    ],
    "temperature": 0.6,
    "max_tokens": 1024
  }'

응답은 OpenAI 스키마를 따릅니다. 일반적으로 다음 필드를 확인하면 됩니다.

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "..."
      }
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}

Apidog로 API 평가 환경 만들기

cURL 문자열을 반복해서 수정하는 대신 Apidog에서 요청을 저장하고 환경 변수로 관리할 수 있습니다.

다음 순서로 구성하세요.

위 cURL 요청을 Apidog로 가져옵니다.
GLM_API_KEY를 환경 변수로 저장합니다.
국제 엔드포인트용 환경을 만듭니다.
Z.ai 중국 본토 엔드포인트용 환경을 별도로 만듭니다.
모델 ID, 프롬프트, temperature, max_tokens를 변수로 분리합니다.
응답을 저장해 호스팅 API 기준선으로 사용합니다.

이렇게 하면 모델 ID나 지역을 전환할 때 요청 본문을 직접 편집하지 않아도 됩니다. 또한 오픈 웨이트 공개 후 자체 배포 결과와 호스팅 API 결과를 같은 요청으로 비교할 수 있습니다.

Python, Node.js, 스트리밍, 오류 처리까지 포함한 예제는 GLM-5.3 API 퀵스타트에서 확인할 수 있습니다.

자주 묻는 질문 (FAQ)

GLM-5.3은 오픈소스인가요?

아직은 아니지만, 오픈 웨이트 공개가 예정돼 있습니다. Zhipu는 API 출시 약 2주 후인 2026년 8월 28일경 Hugging Face에 가중치를 공개하겠다고 밝혔습니다. 그때까지는 호스팅된 API를 통해 접근할 수 있습니다.

GLM-5.3은 GLM-5.2와 어떻게 다른가요?

기본 모델은 동일합니다. 개선 사항은 확장된 후처리에서 비롯됐습니다. Zhipu는 내부 평가에서 코딩 능력 50% 향상, Terminal-Bench 3.0 점수 4.6에서 28.3으로 상승, SWE-Marathon 점수 약 2배 증가를 보고했습니다.

컨텍스트 윈도우, 매개변수 수, 아키텍처는 GLM-5 계열 기준선과 같습니다.

GLM-5.3 비용은 얼마인가요?

출시 시점에 Zhipu는 GLM-5.3 전용 API 가격을 공개하지 않았습니다. 공식 가격 페이지에는 GLM-5.2가 입력 토큰 1M당 1.4달러, 출력 토큰 1M당 4.4달러로 표시되어 있습니다.

비용을 비교할 때는 다음을 함께 측정하세요.

입력 및 출력 토큰 수
작업당 성공률
실패 후 재시도 횟수
평균 응답 시간
사람이 수정하는 데 드는 시간

비용 최적화 전략은 DeepSeek 가격 인상 이후 API 비용 최적화 가이드도 참고할 수 있습니다.

GLM-5.3을 내 하드웨어에서 실행할 수 있나요?

가중치가 공개된 후에는 가능하지만, 하드웨어 요구 사항을 고려해야 합니다. GLM-5 계열은 총 744B 매개변수를 가진 MoE 모델이며 포워드 패스당 약 40B 매개변수가 활성화됩니다. 풀 정밀도 서빙에는 다중 GPU 서버급 하드웨어가 필요할 수 있습니다.

양자화된 커뮤니티 빌드는 요구 사항을 낮출 가능성이 있습니다. 현실적인 배포 계획은 자체 호스팅 준비 가이드에서 확인하세요.

GLM-5.3이 코딩에서 Claude나 GPT보다 더 좋은가요?

작업에 따라 다릅니다. 보고된 결과만 보면 GLM-5.3은 터미널과 에이전트 벤치마크에서 경쟁력이 있습니다.

Terminal-Bench 3.0: 오픈 모델 중 1위
CyberGym: Claude Mythos 5 및 GPT-5.6 Sol보다 약간 높다고 보고
ExploitBench: 54.4%로 최신 모델에 뒤처짐

프로덕션 트래픽을 전환하기 전에 동일한 평가 세트를 두 모델에 적용하세요. 이는 API를 채택하기 전에 테스트하는 방식과 같습니다.

GLM-5.3을 스택에 적용하는 방법

GLM-5.3은 명확한 목표를 가진 전문 릴리스입니다. 코딩 에이전트 성능, 오픈 웨이트 공개 계획, OpenAI 호환 API가 핵심입니다. 현재 공개된 신호는 터미널 및 에이전트 작업에서 강력하지만, ExploitBench 격차와 내부 평가 수치는 별도 검증이 필요합니다.

따라서 지금은 즉시 마이그레이션하기보다 평가 환경을 만드는 단계로 접근하는 것이 적절합니다.

권장 도입 절차

위의 cURL 요청으로 API 연결을 확인합니다.
실제 작업 부하 기반 프롬프트 10~20개를 준비합니다.
성공률, 토큰 사용량, 응답 시간, 재시도 횟수를 저장합니다.
기존 모델과 동일한 조건에서 비교합니다.
오픈 웨이트 공개 후 같은 평가 세트로 자체 호스팅 결과를 비교합니다.

Apidog 다운로드 후 요청 컬렉션과 환경을 구성하면, Z.ai 및 bigmodel.cn 엔드포인트를 쉽게 전환할 수 있습니다. 오늘 저장한 API 응답은 오픈 웨이트 공개 후 자체 배포와 호스팅 API를 비교하는 회귀 기준선이 됩니다.

Gemini 3.7 플래시 가격 가이드: 두 배 인상 전 요금 확정하기

Rihpig — Fri, 14 Aug 2026 07:57:15 +0000

구글은 3.6 Flash 출시 3주 후인 2026년 8월 13일에 Gemini 3.7 Flash를 출시했으며, 이를 “가장 지능적인 워크호스 모델”이라고 부릅니다. API 비용을 지불하는 사람들에게 가장 중요한 세부 사항은 벤치마크가 아닌 가격표에 있습니다. 출시 가격은 1백만 입력 토큰당 $0.75, 1백만 출력 토큰당 $3.75이며 2026년 12월 31일에 만료됩니다. 2027년 1월 1일부터 두 요율은 모두 두 배가 됩니다.

지금 Apidog 사용해 보기

이는 이 모델을 기반으로 구축하는 모든 작업 부하에 예정된 2배의 비용 증가가 있음을 의미합니다. 오늘날 월 $790가 드는 챗봇은 코드, 트래픽 또는 프롬프트 변경 없이 1월에 월 $1,575가 들게 됩니다. 따라서 3.7 Flash 프로젝트 예산을 책정할 때는 정가 대신 두 가지 요금제를 모두 고려해야 합니다.

이 가이드에서는 두 가지 요금제, 세 가지 실제 작업 부하의 토큰 계산 방식, 다른 모델 API와 비교한 가격, 그리고 요금이 두 배가 되기 전에 비용을 절감하는 방법을 설명합니다. 아직 첫 요청을 보내지 않았다면 Gemini 3.7 Flash API 퀵스타트에서 설정 방법을 확인할 수 있습니다. 호출을 시작하면 Apidog은 모든 응답에서 usageMetadata 토큰 수를 표시하므로 아래 추정치를 실제 트래픽과 비교할 수 있습니다.

요약 (TL;DR)

출시 가격: 2026년 12월 31일까지 1백만 입력 토큰당 $0.75, 1백만 출력 토큰당 $3.75입니다.
표준 가격: 2027년 1월 1일부터 입력 $1.50, 출력 $7.50으로 정확히 두 배가 됩니다.
출시 가격은 Gemini 3.6 Flash 출시 당시 비용의 절반입니다.
이 모델은 1백만 토큰 컨텍스트 창에서 텍스트, 이미지, 비디오, 오디오 및 PDF 입력을 처리하며 출력 제한은 64k 토큰입니다.
예시로, 하루 10,000건을 처리하는 챗봇은 출시 가격에서 하루 약 $26.25, 표준 가격에서 하루 약 $52.50가 듭니다.
비용 절감의 핵심은 컨텍스트 캐싱, 출력 제한, 배치 처리, 가벼운 트래픽의 소형 모델 라우팅입니다.

두 가지 가격 등급

Gemini 3.7 Flash는 영구 가격이 아닌 한시적인 할인율로 출시되었습니다.

등급	기간	입력(1백만 토큰당)	출력(1백만 토큰당)
출시 가격	2026년 8월 13일 ~ 2026년 12월 31일	$0.75	$3.75
표준 가격	2027년 1월 1일부터	$1.50	$7.50

두 가지를 우선 확인해야 합니다.

출시 가격은 Gemini 3.6 Flash 출시 당시 비용의 절반입니다. 3.6에서 업그레이드를 검토한다면 3.6에서 3.7 Flash로의 마이그레이션 가이드를 참고해 전환과 회귀 테스트를 진행하세요.
두 등급 모두 출력 토큰 비용이 입력 토큰 비용의 5배입니다. 시스템 프롬프트를 줄이는 것도 도움이 되지만, 폭주하는 출력을 제한하는 편이 더 큰 비용 절감 효과를 냅니다.

위 요금은 AI Studio 키를 통해 청구되는 Gemini API에 적용됩니다. Vertex AI는 별도 SKU와 Google Cloud 청구 체계를 사용하며, 컨텍스트 캐싱과 배치 처리도 별도 항목을 가질 수 있습니다. 예산을 확정하기 전에는 공식 가격 페이지에서 현재 가격을 확인하세요.

실제 작업 부하 비용

1백만 토큰당 가격은 실제 트래픽과 곱해야 의미가 있습니다. 아래 세 가지 예시의 가정을 자체 요청 수와 평균 토큰 수로 교체해 예산을 계산할 수 있습니다.

비용 계산식은 다음과 같습니다.

일일 입력 비용 = (일일 입력 토큰 / 1,000,000) × 입력 단가
일일 출력 비용 = (일일 출력 토큰 / 1,000,000) × 출력 단가
일일 총비용 = 일일 입력 비용 + 일일 출력 비용

작업 부하 1: 고객 지원 챗봇

하루 10,000건의 요청을 가정합니다. 각 요청은 약 2,000개의 입력 토큰(시스템 프롬프트, 짧은 기록 창, 사용자 메시지)을 사용하고 약 300개의 출력 토큰을 반환합니다.

항목	일일 토큰	출시 가격/일	표준 가격/일
입력	20M	$15.00	$30.00
출력	3M	$11.25	$22.50
총계	23M	$26.25	$52.50

30일 기준으로 출시 가격에서는 월 약 $788, 표준 가격에서는 월 약 $1,575입니다. 현재는 대화 턴당 약 0.25센트를 지불하는 셈입니다.

구현 시에는 챗봇 엔드포인트에 출력 상한을 명시적으로 설정하세요.

{
  "generationConfig": {
    "maxOutputTokens": 500
  }
}

지원 응답에 긴 답변이 필요하지 않다면 64k 기본 상한에 의존하지 않는 것이 안전합니다.

작업 부하 2: PDF 문서 파이프라인

Gemini 3.7 Flash는 PDF를 기본적으로 읽을 수 있습니다. GDP.pdf 벤치마크 점수가 3.6 Flash 대비 22.0%에서 34.0%로 상승했으므로, 구글은 문서 추출 작업을 주요 사용 사례로 예상하는 것으로 보입니다.

하루 500개 문서를 가정합니다. 문서당 평균 40,000개의 입력 토큰을 사용하고, 1,000토큰 규모의 구조화된 요약을 생성합니다.

항목	일일 토큰	출시 가격/일	표준 가격/일
입력	20M	$15.00	$30.00
출력	0.5M	$1.88	$3.75
총계	20.5M	$16.88	$33.75

월 비용은 현재 약 $506이며, 1월부터는 약 $1,013입니다. 긴 문서와 짧은 요약의 조합에서는 입력 비용이 대부분을 차지합니다. 이 유형의 작업에는 캐싱과 배치 처리가 가장 큰 영향을 줍니다.

작업 부하 3: 에이전트 루프

에이전트는 호출 수를 증폭시킵니다. 하루 200개의 작업을 가정하고, 각 작업이 평균 12회의 모델 호출을 수행한다고 가정합니다. 각 호출은 증가하는 컨텍스트와 도구 결과를 포함해 8,000개의 입력 토큰을 사용하고, 400개의 출력 토큰을 반환합니다.

항목	일일 토큰	출시 가격/일	표준 가격/일
입력	19.2M	$14.40	$28.80
출력	0.96M	$3.60	$7.20
총계	20.16M	$18.00	$36.00

월 비용은 출시 가격에서 $540, 표준 가격에서 $1,080입니다. 에이전트 작업에서는 호출 수와 컨텍스트 길이가 함께 증가합니다. 12회 호출에서 20회 호출로 증가하면 비용도 67% 늘어나지만, 가격표만 봐서는 이런 증폭을 알기 어렵습니다.

또한 64k 출력 제한은 호출당 최악의 경우를 현재 약 $0.24, 표준 가격에서는 약 $0.48로 제한합니다. 재시도 루프가 매번 최대 출력을 사용하면 빠르게 비싸질 수 있으므로, 단계별 출력 제한과 재시도 횟수 제한을 함께 적용하세요.

에이전트 작업 비용
= 작업 수 × 작업당 호출 수 × 호출당 평균 토큰 비용

3.7 Flash 가격 비교

공급업체 간 정확한 토큰당 비교는 빠르게 바뀌므로, 아래 내용은 고정 가격표보다 포지셔닝으로 보는 편이 좋습니다.

Gemini 3.7 Flash는 워크호스 등급에 속합니다. Gemini Pro 라인, Claude의 대규모 모델, OpenAI 플래그십 등급처럼 최첨단 모델보다 저렴하면서도, 얼마 전 플래그십 모델이 기록했던 벤치마크 점수와 겹칩니다. 예를 들어 DeepSWE v1.1은 65.3%, WebDev Arena Elo는 1588점입니다.

핵심은 대부분의 프로덕션 트래픽이 최첨단 모델을 항상 필요로 하지 않는다는 점입니다. 출시 할인 기간은 자체 워크로드에서 이 가정을 검증할 수 있는 기간입니다.

경쟁 환경도 고려해야 합니다. 보급형 공급업체의 가격은 변동할 수 있습니다. DeepSeek의 API 가격 인상 사례는 DeepSeek 가격 인상 및 비용 최적화 가이드에서 확인할 수 있습니다. Gemini도 마찬가지로 가격 변동 가능성을 예산에 반영해야 하며, 여기서는 구글이 인상 날짜와 금액을 미리 공개했습니다.

프로토타입 비용이 $3에서 $6로 바뀌는 것은 큰 문제가 아닐 수 있습니다. 하지만 월 $10,000 파이프라인이 $20,000가 되는 경우는 사전에 계획해야 할 운영 비용입니다.

토큰 지출을 줄이는 5가지 방법

출력 토큰이 입력 토큰보다 5배 비싸고, 2027년 1월에 전체 요금이 두 배가 된다는 점을 기준으로 최적화 우선순위를 정하세요.

1. 엔드포인트별 출력 토큰 제한

generationConfig.maxOutputTokens를 엔드포인트에 필요한 최소값으로 설정하세요. 지원 응답에는 보통 500토큰 이상이 필요하지 않습니다.

{
  "generationConfig": {
    "maxOutputTokens": 500
  }
}

출력 토큰은 입력보다 5배 비싸므로, 이 변경이 가장 높은 비용 절감 효과를 낼 수 있습니다.

2. 정적 컨텍스트 캐싱

모든 요청에서 동일한 3,000토큰 시스템 프롬프트와 정책 문서를 반복 전송한다면, 같은 입력 토큰에 매번 전체 비용을 지불하게 됩니다. 컨텍스트 캐싱을 적용하면 반복 토큰에 할인된 요율을 적용할 수 있습니다.

현재 지원 범위와 요금은 Gemini API 문서에서 확인하세요. 위 챗봇 예시에서 1,500토큰의 정적 접두사를 캐싱하면 입력 비용을 거의 절반까지 줄일 수 있습니다.

3. 비대화형 작업 배치 처리

문서 파이프라인은 보통 1초 미만의 응답 시간이 필요하지 않습니다. 배치 처리는 지연 시간을 허용하는 대신 할인된 요금을 활용할 수 있으므로, 야간 문서 처리와 같은 작업에 적합합니다.

다음처럼 요청을 분리하세요.

실시간 경로: 사용자 대화, 즉시 응답이 필요한 작업
배치 경로: 문서 요약, 분류, 대량 추출, 야간 처리

4. 경로별 모델 크기 조정

모든 요청에 3.7 Flash를 사용할 필요는 없습니다. 분류, 라우팅, 짧은 추출 작업은 Flash-Lite 등급 모델에서 더 저렴하게 처리할 수 있습니다.

3.7 Flash는 다음처럼 성능 가치가 큰 경로에 집중하세요.

다단계 계획
디버깅
복잡한 도구 호출 체인
긴 문서 추론
품질 요구가 높은 생성 작업

5. 무료 티어에서 프로토타입 제작

AI Studio의 무료 할당량을 사용해 프롬프트와 응답 스키마를 먼저 확정하세요. 청구 토큰을 사용하기 전에 출력 길이, 구조화된 응답, 실패 처리 방식을 검증할 수 있습니다.

무료 Gemini API 액세스 가이드에서 무료 경로의 범위와 제한을 확인할 수 있습니다.

Apidog로 엔드포인트별 지출 추적

추정치는 예산 수립에 도움이 되지만, 실제 요청별 측정이 있어야 예산을 유지할 수 있습니다. Gemini 응답에는 프롬프트 및 출력 토큰 수를 포함하는 usageMetadata 블록이 있으므로 API 테스트 계층을 비용 측정기로도 활용할 수 있습니다.

Apidog에서는 다음 워크플로우를 구성하세요.

프로덕션 엔드포인트별로 요청을 컬렉션에 저장합니다.
- 챗봇 턴
- 문서 요약
- 에이전트 단계
API 키를 GEMINI_API_KEY 환경 변수에 바인딩합니다.
실제 페이로드로 요청을 실행하고 응답의 아래 값을 기록합니다.

usageMetadata.promptTokenCount
usageMetadata.candidatesTokenCount

토큰 수에 대한 어설션을 추가합니다. 예를 들어 채팅 엔드포인트의 입력 토큰이 2,500을 초과하면 테스트가 실패하도록 설정할 수 있습니다.

promptTokenCount <= 2500
candidatesTokenCount <= 500

프롬프트, 도구 정의, 응답 스키마를 변경할 때마다 시나리오를 다시 실행합니다.

토큰 수는 대기 시간처럼 회귀합니다. 차이점은 토큰 회귀가 나중에 청구서로 나타난다는 점입니다. 측정된 카운트에 이 가이드의 등급별 가격을 곱하면 추측이 아닌 실제 응답 기준의 엔드포인트별 비용을 계산할 수 있습니다.

어설션 기반 API 테스트 스위트를 운영 중이라면 이 패턴을 쉽게 적용할 수 있습니다. QA 엔지니어를 위한 API 테스트 가이드에서 전체 서비스에 걸쳐 시나리오를 구성하는 방법을 확인하세요.

자주 묻는 질문

Gemini 3.7 Flash 가격은 언제 두 배가 되나요?

2027년 1월 1일입니다. 1백만 입력 토큰당 $0.75, 1백만 출력 토큰당 $3.75의 출시 가격은 2026년 12월 31일까지 적용됩니다. 이후 표준 가격인 입력 $1.50, 출력 $7.50으로 변경됩니다.

구글이 출시 시점에 두 요금제를 모두 공개했으므로, 이 인상은 추측이 아니라 예정된 가격 변경입니다.

Gemini 3.7 Flash가 Gemini 3.6 Flash보다 저렴한가요?

출시 시점에는 그렇습니다. 3.7 Flash의 출시 가격은 3.6 Flash 출시 가격의 절반이며, 벤치마크도 전반적으로 향상되었습니다. DeepSWE v1.1은 49.0%에서 65.3%로 상승했습니다.

자세한 사양과 벤치마크는 Gemini 3.7 Flash 빠른 참조에서 확인할 수 있습니다.

Vertex AI에도 출시 가격이 적용되나요?

이 가이드의 요금은 AI Studio 키를 통해 청구되는 Gemini API 요금입니다. Vertex AI는 자체 SKU와 기업 약관을 통해 Google Cloud에서 청구됩니다.

Vertex에서 프로덕션 트래픽을 실행한다면 동일한 가격이 적용된다고 가정하지 말고, GCP 청구 콘솔과 공식 가격 페이지에서 현재 가격을 확인하세요.

입력 토큰 청구에는 무엇이 포함되나요?

보내는 모든 입력이 포함됩니다.

텍스트
이미지
비디오
오디오
PDF 페이지

이 데이터는 토큰으로 변환되어 입력 요율로 청구됩니다. 긴 문서와 미디어가 많은 요청에서는 입력 비용이 예상보다 커질 수 있습니다. 실제 사용량은 각 응답의 usageMetadata 블록에서 확인하세요.

요청을 보내기 전에 토큰을 어떻게 예측하나요?

API의 countTokens 엔드포인트로 생성 없이 페이로드를 측정하거나, 대표 요청을 몇 건 실행한 뒤 응답의 usageMetadata를 확인하세요.

어떤 방식을 사용하든 실제 페이로드로 측정해야 합니다. 다른 공급업체의 토크나이저 기준은 Gemini 모델 제품군에 그대로 적용되지 않을 수 있습니다.

3.7 Flash가 스택에 들어가는 위치

출시 가격의 Gemini 3.7 Flash는 강력한 워크호스 모델을 낮은 비용으로 검증할 수 있는 기간을 제공합니다. 실용적인 운영 전략은 다음과 같습니다.

워크호스 트래픽을 3.7 Flash로 이전합니다.
출시 할인 기간 동안 엔드포인트별 실제 토큰 소비량을 측정합니다.
측정 데이터를 기준으로 3.7 Flash에 유지할 경로와 더 가벼운 모델로 이전할 경로를 구분합니다.
표준 요금이 적용되기 전에 월 비용 시나리오를 계산합니다.

측정에는 도구가 필요합니다. Apidog를 다운로드해 Gemini 요청, 환경 변수, 토큰 어설션 및 비용 확인을 하나의 작업 공간에서 관리하세요. 그러면 1월 청구서는 나중에 발견하는 숫자가 아니라 미리 예측한 숫자가 됩니다.

DEV Community: Rihpig

클로드 2026년 무료 사용법: 가능한 모든 방법

2026년 무료 Claude 사용법: Sonnet 5, Claude Code, API까지

Claude는 무료인가요?

옵션 1: claude.ai 무료 요금제

무료 할당량을 효율적으로 사용하는 방법

옵션 2: Claude Code 게스트 패스

옵션 3: Apidog로 테스트하는 무료 API 크레딧

옵션 4: 이미 사용하는 도구에서 Claude 사용하기

옵션 5: 클라우드 제공업체 평가판 크레딧

무료 Claude의 제한 사항

자주 묻는 질문

무료로 시작하고, 똑똑하게 테스트하세요

그록 2026년 무료 사용법: 가능한 모든 방법

Grok은 무료인가요? 2026년 무료 사용·API 크레딧 가이드

Grok은 무료인가요?

grok.com과 X 앱에서 무료로 채팅하기

무료 사용량 제한

무료 사용자는 어떤 모델을 쓰나요?

xAI는 무료 API 크레딧을 제공하나요?

API 비용에서 주의할 점

Grok Imagine과 Voice는 무료인가요?

Grok Imagine

Grok Voice

무료 Grok으로 할 수 없는 것

Apidog로 API 크레딧을 오래 사용하는 방법

자주 묻는 질문

X 프리미엄 없이도 Grok은 무료인가요?

Grok API는 무료인가요?

현재 무료 Grok 모델은 무엇인가요?

Grok에서 이미지를 무료로 만들 수 있나요?

요약

노트북LM 2026년 활용법: 구글의 무료 연구 도구 실용 가이드

NotebookLM 사용법: 무료 기능, 소스 제한, 개발자 API 문서 활용법

NotebookLM이란? 무료인가요?

NotebookLM과 Gemini Notebook

첫 노트북 설정하기

소스 종류와 제한 사항

추가할 수 있는 소스

무료 플랜의 소스 한도

알아두어야 할 문제

시간을 투자할 가치가 있는 기능

오디오 개요

비디오 개요

마인드 맵

보고서, 플래시카드, 퀴즈

무료 플랜과 유료 플랜 비교

업그레이드할 시점

개발자 워크플로우: API 문서 분석하기

NotebookLM의 한계

자주 묻는 질문

NotebookLM이 업로드한 데이터로 학습하나요?

다른 사람과 노트북을 공유할 수 있나요?

사용할 수 있는 NotebookLM API가 있나요?

어떤 언어를 지원하나요?

마무리

DeepSeek 무료? 챗, API 요금과 2026년 모든 무료 이용법

DeepSeek은 무료인가요?

무료 채팅 앱과 제한 사항

DeepSeek API 가격

비용을 줄이는 세 가지 방법

무료 또는 거의 무료인 API 경로

DeepSeek을 로컬에서 무료로 실행하기

채팅, API, 로컬 중 무엇을 선택할까?

실제 호출은 한 번만, 나머지는 Apidog로 모의하기

자주 묻는 질문

결론

DeepSeek V4-Flash-Vision API 사용법 (이미지 입력 가이드)

DeepSeek V4-Flash Vision Exp API 사용법: 이미지 입력, 비용, 제한 사항

deepseek-v4-flash-vision-exp란 무엇인가

가격: 텍스트 모델과 동일한 플래시 요율

이미지를 전송하는 세 가지 방법

1. Base64 인라인 이미지

2. 외부 URL

3. Files API의 file_id 참조

detail 매개변수 설정

프로덕션 전에 확인할 제한 사항

Exp가 프로덕션 코드에 의미하는 것

모델 ID를 한 곳에서 관리하기

텍스트 전용 대체 모델 유지하기

`deepseek-v4-flash-vision-exp`란 무엇인가

3. Files API의 `file_id` 참조

`detail` 매개변수 설정

`Exp`가 프로덕션 코드에 의미하는 것

`deepseek-v4-flash-vision-exp`는 무료인가요?

`deepseek-v4-flash`를 대체하나요?

`my-gateway`

`apiKeyEnv`

`api`

`baseURL`

`models`

`input`

`compat`

`developer` 역할 오류

`baseURL`이 잘못되었거나 연결할 수 없음

사용자 지정 엔드포인트가 `curl`에서는 없던 오류를 반환합니다. 어떻게 해결하나요?

단계 1: `AGENTS.md`에 Apidog CLI 명령 추가

DeepSeek Harness는 기본적으로 `AGENTS.md`를 읽나요?