구글 클라우드(Google Cloud)로 NL2SQL(Text2SQL) 에이전트 사용하기 — 4가지 방법과 선택 기준

“SQL을 몰라도 데이터에 직접 질문할 수 있게 해주세요.”

데이터 조직이라면 한 번쯤 받아본 요청일 것입니다. 자연어 질문을 SQL로 바꿔 실행하고 결과를 설명해 주는 것을 NL2SQL(Text2SQL)이라고 하는데, LLM 등장 이후 가장 수요가 많은 기업용 AI 유스케이스 중 하나가 되었습니다.

구글 클라우드(GCP)에서 NL2SQL 에이전트를 도입하는 방법은 하나가 아닙니다. 완제품을 그대로 쓰는 방법부터 직접 만드는 방법까지 4가지 선택지가 있고, 각각 대상 사용자와 통제 수준이 다릅니다. 이 글에서는 4가지 방법의 특징과 장단점, 그리고 선택 기준을 정리합니다.


시작 전에 — NL2SQL이 어려운 진짜 이유

방법을 비교하기 전에 이것부터 짚어야 합니다. NL2SQL의 난이도는 SQL 문법이 아니라 컨텍스트에서 나옵니다.

  • “지난달 매출”에서 매출은 어느 테이블의 어느 컬럼인가? 환불은 빼는가?
  • 테이블이 3,000개인데 LLM에게 어떤 스키마를 보여줄 것인가?
  • 생성된 SQL이 문법은 맞지만 의미가 틀렸다면 누가 어떻게 검증하는가?

4가지 방법의 차이는 결국 “이 문제들을 누가 해결해 주는가(Google인가, 나인가)”의 차이입니다.


방법 1 — BigQuery Agent: 콘솔 안에서 바로 쓰기

무엇인가.

BigQuery Studio에 내장된 에이전트 기능입니다. 데이터 캔버스나 SQL 에디터에서 자연어로 질문하면 Gemini가 SQL을 생성·설명·수정해 줍니다. 별도 구축 없이 BigQuery를 쓰고 있다면 바로 사용할 수 있습니다.

장점

  • 설정이 거의 필요 없습니다. 가장 빠르게 시작하는 방법입니다.
  • 콘솔에 통합되어 있어 생성된 SQL을 바로 확인·수정·실행할 수 있습니다.
  • 스키마 컨텍스트를 BigQuery가 자동으로 활용합니다.

단점

  • BigQuery 콘솔에 들어올 수 있는 사람만 쓸 수 있습니다. 결국 데이터 실무자용 생산성 도구이지, 현업에게 열어주는 셀프서비스가 아닙니다.
  • 사내 앱이나 챗봇에 임베드할 수 없습니다.
  • 생성된 SQL의 의미 검증은 전적으로 사용자 몫입니다.

한 줄 요약: 분석가와 데이터 엔지니어의 SQL 작성 속도를 높이는 도구입니다.


방법 2 — Conversational Analytics API: 내 앱에 임베드하기

무엇인가.

개발자용 API입니다(Gemini Data Analytics API). BigQuery 테이블이나 Looker 익스플로어를 데이터 소스로 하는 데이터 에이전트를 정의하고, 시스템 지침(용어 정의, 지표 규칙, few-shot 예시 등)을 YAML로 등록해 두면, 멀티턴 대화로 질문 → SQL 생성 → 실행 → 요약·차트까지 API 응답으로 받을 수 있습니다. 사내 포털, 슬랙 봇, 고객용 대시보드 등 원하는 곳에 임베드합니다.

장점

  • NL2SQL 파이프라인(스키마 해석, SQL 생성, 실행, 시각화)을 Google이 관리합니다. 직접 프롬프트 엔지니어링을 하지 않아도 됩니다.
  • 시스템 지침으로 우리 회사의 용어와 지표 정의를 주입할 수 있어 순수 프롬프트 방식보다 정확도가 좋습니다.
  • Looker를 데이터 소스로 쓰면 시맨틱 레이어(LookML)의 지표 정의를 그대로 타므로 “매출이 뭐냐” 문제가 구조적으로 해결됩니다.
  • UI를 우리가 만들므로 사용자 경험을 완전히 통제할 수 있습니다.

단점

  • NL2SQL 코어 로직(모델 선택, 프롬프트, 검증 루프)은 블랙박스에 가깝습니다. 정확도가 아쉬운 케이스를 만나면 시스템 지침 튜닝 외에 손 쓸 방법이 제한적입니다.
  • 프론트엔드와 권한 처리는 직접 개발해야 합니다.

한 줄 요약: NL2SQL 엔진은 빌려 쓰고, 제품 경험만 직접 만들고 싶을 때 가장 균형 잡힌 선택입니다.


방법 3 — Gemini Enterprise: 노코드로 전사 배포하기

무엇인가.

지난 글에서 다룬 기업용 AI 플랫폼(SaaS)입니다. BigQuery를 데이터 소스로 연결하면 전 직원이 챗 인터페이스에서 데이터에 질문할 수 있습니다. 내부적으로는 Conversational Analytics의 데이터 에이전트가 동작하는 구조입니다.

장점

  • 가장 빠른 전사 배포. 개발 없이 커넥터 연결과 권한 설정만으로 현업에게 열어줄 수 있습니다.
  • 문서 검색, 사내 지식 Q&A 등 다른 에이전트 기능과 한 인터페이스에서 함께 제공됩니다.
  • 좌석 기반 과금이라 비용 예측이 쉽습니다.

단점

  • 커스터마이징 여지가 가장 적습니다. 지표 정의 주입, 검증 로직 추가, UI 변경 모두 제한적입니다.
  • 모델과 처리 위치를 선택할 수 없습니다. 지난 글에서 정리했듯 소버린티 요건이 있는 금융권·국가핵심기술 기업의 규제 데이터에는 쓸 수 없습니다.
  • 정확도가 아쉬워도 튜닝 수단이 사실상 없습니다.

한 줄 요약: 비규제 데이터의 전사 셀프서비스 분석을 가장 싸고 빠르게 여는 방법입니다.


방법 4 — Agent Platform으로 직접 만들기

무엇인가.

Gemini Enterprise의 에이전트 플랫폼(ADK 기반 개발 + Agent Engine 배포)으로 NL2SQL 에이전트를 직접 개발하는 방법입니다. 스키마 검색(RAG), few-shot 예시 선택, SQL 생성, dry-run 검증, 실패 시 재생성 루프까지 전부 우리가 설계합니다. 완성한 에이전트는 Gemini Enterprise에 등록해 챗 인터페이스로 노출할 수도 있고, 독립 API로 서비스할 수도 있습니다.

장점

  • 모든 것을 통제합니다. 모델 버전, 프롬프트, 스키마 컨텍스트 전략, 검증 로직, 오류 처리 — 정확도를 끌어올릴 수 있는 모든 레버가 우리 손에 있습니다.
  • BigQuery dry-run으로 SQL을 실행 전에 검증하고, 실패하면 오류 메시지를 넣어 재생성하는 자가 수정 루프를 넣을 수 있습니다. 프로덕션급 정확도는 대부분 여기서 나옵니다.
  • 행 수준 권한, 감사 로그, 쿼리 비용 가드레일 같은 거버넌스 요건을 원하는 대로 구현할 수 있습니다.
  • Vertex AI regional endpoint를 직접 선택하므로 처리 위치를 고정할 수 있습니다. 소버린티 요건이 있는 조직이 선택할 수 있는 사실상 유일한 방법입니다.

단점

  • 개발·운영 비용이 가장 큽니다. NL2SQL 품질에 대한 책임도 전부 우리가 집니다.
  • 에이전트 평가 체계(질문-정답 SQL 셋, 회귀 테스트)를 함께 만들지 않으면 품질 관리가 불가능합니다. 만들 것이 에이전트 하나가 아니라는 뜻입니다.

한 줄 요약: 정확도·거버넌스·소버린티가 크리티컬한 워크로드를 위한 방법입니다.


한눈에 비교

구분 1. BigQuery Agent 2. Conversational Analytics API 3. Gemini Enterprise 4. 직접 개발 (Agent Platform)
대상 사용자 데이터 실무자 우리 서비스의 사용자 전 직원 (현업) 요건에 따라 자유
개발 필요량 없음 중간 (임베드 개발) 없음 큼 (에이전트 전체)
앱 임베드 불가 가능 불가 (제공 UI 사용) 가능
지표 정의 주입 제한적 시스템 지침·Looker 제한적 자유
정확도 튜닝 불가 제한적 불가 자유 (검증 루프 포함)
처리 위치 통제 (소버린티) 리전 종속 제한적 불가 가능 (regional endpoint)
시작 속도 즉시 수 주 수 일 수 개월

선택 가이드

시나리오별로 매핑하면 이렇습니다.

  1. 분석가 생산성이 목적 → 방법 1. 이미 있는 기능이니 그냥 켜세요.
  2. 자사 서비스·사내 포털에 분석 챗봇 임베드 → 방법 2. 엔진을 빌려 쓰고 경험에 집중하세요. Looker가 있다면 반드시 함께 쓰세요.
  3. 비규제 데이터의 전사 셀프서비스 → 방법 3. 단, 정확도 튜닝이 안 되므로 중요 의사결정용 지표는 대시보드로 이원화하세요.
  4. 금융권·규제 데이터, 또는 정확도가 비즈니스 크리티컬 → 방법 4. 처리 위치 통제와 검증 루프가 필요하다면 다른 선택지가 없습니다.

그리고 어떤 방법을 고르든 공통으로 적용되는 진실이 하나 있습니다. NL2SQL의 정확도 상한선은 모델이 아니라 메타데이터 품질이 결정합니다. 테이블·컬럼 설명, 지표 정의, 용어 사전이 없으면 4번 방법으로도 좋은 결과를 얻을 수 없습니다. 에이전트 도입 전에 데이터 사전과 시맨틱 레이어부터 정비하는 것이 가장 수익률 높은 투자입니다.


마무리

  1. 4가지 방법은 경쟁 관계가 아니라 스펙트럼입니다. 완제품(1, 3)과 반제품(2), 직접 개발(4)은 대상 사용자와 통제 수준이 다를 뿐입니다. 실제로는 1+3, 2+4처럼 조합해서 쓰게 됩니다.
  2. 통제가 필요한 만큼만 만드세요. 검증 루프와 소버린티가 필요 없다면 직접 개발은 과잉 투자입니다. 반대로 규제 데이터라면 처음부터 방법 4로 가야 재작업이 없습니다.
  3. 메타데이터가 먼저입니다. 어떤 방법이든 지표 정의와 데이터 사전 없이는 “그럴듯하지만 틀린 SQL”을 벗어날 수 없습니다.

제품 이름과 기능 범위는 빠르게 바뀌는 영역입니다. 이 글의 비교 프레임(대상 사용자 × 통제 수준)으로 후보를 좁히되, 세부 기능과 리전 지원은 도입 시점의 최신 문서로 확인하시기 바랍니다.

Gemini Enterprise는 소버린티를 만족하는가?

지난 글에서 소버린과 소버린티의 개념, 그리고 Google Cloud에서 규제 워크로드를 설계할 때 챙겨야 할 것들을 정리했습니다. 그 글을 읽으신 분들에게 요즘 가장 많이 받는 질문이 이것입니다.

“그러면 Gemini Enterprise를 도입하면 되나요?”

결론부터 말씀드리면, 소버린티 요건이 있는 워크로드라면 지금은 아닙니다. 왜 그런지 쉽고 간단하게 설명하겠습니다.


Gemini Enterprise가 뭔가요?

Gemini Enterprise는 Google이 판매하는 기업용 AI 에이전트 플랫폼(SaaS)입니다. 한 문장으로 요약하면 “회사 전 직원에게 사내 데이터를 아는 AI 비서를 깔아주는 제품”입니다.

사내 데이터 연결

Google Workspace, Microsoft 365, Salesforce, Jira 같은 업무 시스템에 커넥터로 연결해서, 직원이 챗으로 사내 문서와 데이터를 검색하고 질문할 수 있습니다.

에이전트 빌더

코딩 없이 업무용 에이전트를 만들고 조직에 배포할 수 있습니다. Deep Research 같은 Google이 만든 에이전트도 기본 제공됩니다.

좌석(seat) 단위 구독

API 종량제가 아니라 사용자당 월 요금을 내는 SaaS 모델입니다.

여기서 중요한 것은 Vertex AI와의 차이입니다.

구분 Vertex AI Gemini Enterprise
제품 성격 개발자용 빌딩블록 (플랫폼) 완성형 SaaS
인프라 통제 고객이 리전·엔드포인트·모델을 직접 선택 Google이 운영, 고객은 기능을 사용
도입 방식 직접 설계·구축 구독하고 커넥터 연결

Vertex AI가 “부엌과 재료를 빌려주는 것”이라면, Gemini Enterprise는 “완성된 요리를 배달받는 것”입니다. 편한 만큼, 주방이 어디에 있는지는 고를 수 없습니다.


왜 소버린티를 만족하지 못하는가

이유는 두 가지이고, 둘 다 구조적인 문제입니다.

1. 한국 리전 endpoint가 없습니다.

Gemini Enterprise는 서울 리전(asia-northeast3)을 지정해서 쓸 수 없습니다. 데이터 레지던시 선택지가 미국·EU 등 일부 멀티리전 수준에서 제공될 뿐, “내 회사 데이터는 한국 안에서만 저장·처리하라”고 지정하는 옵션 자체가 없습니다. 커넥터로 연결한 사내 문서의 인덱스가 어디에 저장되는지, 직원의 질문이 어느 리전에서 처리되는지를 국내로 고정할 방법이 없다는 뜻입니다.

2. LLM을 선택할 수 없습니다.

Vertex AI에서는 regional endpoint로 “이 모델을 이 리전에서 돌려라”를 고객이 결정합니다. 반면 Gemini Enterprise는 SaaS라서 어떤 모델 버전이 어느 리전의 인프라에서 추론을 수행하는지가 전적으로 Google의 운영 정책에 따릅니다. 고객이 모델도, 처리 위치도 고를 수 없습니다. 지난 글에서 “AI 소버린티의 핵심은 LLM이 어디에서 도는가”라고 했는데, Gemini Enterprise는 이 질문에 고객이 답할 수단이 없는 제품입니다.

지난 글의 체크리스트에 대입해 보면 이렇게 됩니다.

소버린티 체크 항목 Gemini Enterprise
데이터 저장 위치를 국내로 고정 불가 (서울 리전 미지원)
LLM 처리 위치를 국내로 고정 불가 (처리 리전 선택 기능 없음)
모델·엔드포인트 선택권 없음 (Google 운영 정책에 종속)
처리 위치에 대한 감사 입증 불가

금융권·국가핵심기술 기업이라면

금융권.

금융회사는 클라우드 이용 시 데이터가 어디에서 저장·처리되는지를 입증해야 합니다. “SaaS라서 처리 위치를 알 수 없습니다”는 중요도 평가와 감사를 통과할 수 없는 답변입니다. 규제 대상 데이터를 다루는 업무라면 Gemini Enterprise는 검토 대상에서 제외하는 것이 맞습니다.

국가핵심기술 기업.

더 명확합니다. 기술자료가 포함된 질문이 국외 리전에서 처리될 수 있다는 것 자체가 기술 유출 리스크로 해석될 수 있습니다. 처리 위치를 통제할 수 없는 SaaS에 국가핵심기술 관련 데이터를 연결하는 것은 선택지가 아닙니다.

그러면 아예 못 쓰는가?

그렇지는 않습니다. 규제 데이터가 들어가지 않는 일반 업무 — 공개 자료 리서치, 일반 문서 작성 보조 같은 영역에서는 충분히 쓸 수 있습니다. 다만 이 경우에도 직원들이 규제 데이터를 붙여넣지 못하도록 DLP와 커넥터 범위 통제를 반드시 함께 설계해야 합니다.

규제 워크로드의 대안

지난 글에서 다룬 그대로입니다. Vertex AI regional endpoint로 직접 구축하는 것이 기본이고, 최고 수위 데이터라면 GDC air-gapped나 오픈 모델 자체 서빙으로 가야 합니다.


마무리

  1. Gemini Enterprise는 좋은 제품입니다. 사내 데이터를 아는 AI 비서를 가장 빠르게 전사 배포하는 방법입니다.
  2. 하지만 소버린티 요건과는 맞지 않습니다. 한국 리전 endpoint가 없고, LLM과 처리 위치를 고객이 선택할 수 없기 때문입니다. 금융권·국가핵심기술 기업의 규제 워크로드에는 쓸 수 없습니다.
  3. 도입하려면 데이터 등급으로 선을 그으세요. 규제 데이터가 닿지 않는 업무에 한정하고, 규제 워크로드는 Vertex AI regional endpoint 기반으로 별도 설계해야 합니다.

SaaS의 리전 지원과 레지던시 옵션은 빠르게 바뀝니다. 이 글은 작성 시점 기준이니, 도입 검토 시점에 한국 리전 지원과 처리 위치 커밋 로드맵을 어카운트 팀에 반드시 재확인하시기 바랍니다.

소버린과 소버린티, 그리고 Google Cloud — 국가핵심기술과 금융권 요건을 만족하는 AI·데이터 설계

요즘 클라우드 업계에서 가장 많이 들리는 단어가 “소버린(sovereign)”입니다. 소버린 클라우드, 소버린 AI, AI 소버린티… 비슷한 단어들이 섞여 쓰이다 보니 정작 “그래서 우리 회사는 뭘 해야 하는데?”라는 질문에는 답이 잘 나오지 않습니다.

이 글에서는 용어를 먼저 정리하고, Google Cloud에서 국가핵심기술을 다루는 기업과 금융권 기업이 소버린티 요건을 만족하려면 AI와 데이터 영역에서 구체적으로 무엇을 챙겨야 하는지 정리합니다. 특히 많은 분들이 놓치는 LLM processing의 리전 위치 문제를 중심으로 다룹니다.


소버린? 소버린티? 용어부터 정리

두 단어는 품사가 다릅니다.

소버린티(sovereignty, 주권)

상태 또는 능력입니다. 내 데이터가 어디에 있는지, 누가 접근할 수 있는지, 어떤 법률의 적용을 받는지, 서비스가 끊겼을 때 스스로 운영을 지속할 수 있는지에 대한 통제권을 말합니다.

소버린(sovereign)

형용사입니다. “소버린 클라우드”는 그런 주권 요건을 만족하도록 설계·운영되는 클라우드를 가리킵니다.

즉 소버린티는 목표이고, 소버린 클라우드는 그 목표를 달성하기 위한 수단입니다. Google Cloud는 소버린티를 세 계층으로 나눠서 설명하는데, 이 프레임이 실무에서 요건을 분해할 때 유용합니다.

계층 질문 대표 수단
데이터 소버린티 내 데이터가 어디에 저장·처리되고, 누가 열람할 수 있는가? 데이터 레지던시, CMEK/EKM, Access Transparency
운영 소버린티 클라우드를 운영·지원하는 사람이 누구이고 어디에 있는가? Assured Workloads, 파트너 운영 모델
소프트웨어(기술) 소버린티 특정 사업자 없이도 워크로드를 계속 돌릴 수 있는가? 오픈소스 기반 스택, GDC, 오픈 모델

“소버린 클라우드 = 국내 리전에 데이터 저장” 정도로 이해하면 첫 번째 계층의 절반만 본 것입니다. 특히 AI 워크로드에서는 저장 위치보다 처리 위치가 더 어려운 문제입니다. 뒤에서 자세히 다룹니다.


왜 지금 이슈인가 — 국가핵심기술과 금융권

한국에서 소버린티 논의가 뜨거운 영역이 두 곳입니다.

국가핵심기술.

산업기술보호법상 국가핵심기술(반도체, 디스플레이, 이차전지, 조선, 자동차 등)을 보유한 기업이 관련 기술자료를 해외 사업자의 클라우드에 올리는 것은 기술 유출 관점에서 민감한 행위로 해석될 수 있습니다. 설계 도면이나 공정 데이터를 LLM에 넣어 요약·검색하게 만드는 순간, “그 프롬프트는 어느 나라 서버에서 처리되는가”가 컴플라이언스 질문이 됩니다.

금융권.

전자금융감독규정과 금융분야 클라우드컴퓨팅서비스 이용 가이드에 따라 금융회사는 클라우드 이용 시 중요도 평가, CSP 안전성 평가(금융보안원), 업무 위수탁 보고 등의 절차를 거칩니다. 망분리 규제가 단계적으로 개선되면서 생성형 AI를 업무에 활용할 수 있는 길이 열렸지만, 그 대가로 데이터 처리 위치와 접근 통제에 대한 입증 책임은 오히려 더 명확해졌습니다. “글로벌 SaaS라서 어디서 처리되는지 모릅니다”는 답변이 통하지 않는 환경입니다.

두 영역의 공통점은 이것입니다. “데이터가 국내에 저장됩니다”만으로는 부족하고, 저장·처리·접근·운영 전 과정을 설명할 수 있어야 한다는 것입니다.


Google Cloud의 소버린 스펙트럼

Google Cloud는 소버린티 요구 수준에 따라 단계적인 선택지를 제공합니다. 전부 아니면 전무가 아니라 스펙트럼입니다.

단계 구성 적합한 경우
1. 리전 + 통제 강화 서울 리전(asia-northeast3) + Assured Workloads + CMEK/EKM + VPC-SC 금융권 일반 워크로드, 대부분의 규제 대응
2. Sovereign Controls 파트너 감독 하에 운영되는 소버린 구성 (유럽의 T-Systems 모델 등) 운영 주권까지 계약으로 입증해야 하는 경우
3. Google Distributed Cloud (Connected) 고객 데이터센터에 Google Cloud 인프라 설치, Google 클라우드와 연결 데이터는 온프레미스, 관리는 클라우드
4. Google Distributed Cloud (Air-gapped) 인터넷과 완전히 단절된 독립 운영 환경 국가핵심기술, 국방·공공 최고 수위 요건

포인트는 요건에 맞는 최소 단계를 선택하는 것입니다. 모든 워크로드를 air-gapped로 몰면 클라우드를 쓰는 의미가 없어지고, 반대로 국가핵심기술 데이터를 일반 리전 구성에 올리면 감사에서 막힙니다. 데이터 분류(classification)가 선행되어야 하는 이유입니다.


데이터 영역에서 신경 쓸 것 4가지

AI 얘기 전에 기초 공사부터 확인해야 합니다. 이 4가지가 안 되어 있으면 AI 소버린티는 논할 수 없습니다.

1. 데이터 레지던시를 조직 정책으로 강제. 콘솔에서 리전을 서울로 고르는 것과, Organization Policy의 리소스 위치 제약(Resource Location Restriction)으로 asia-northeast3 외 리소스 생성을 원천 차단하는 것은 다릅니다. 규제 대응은 후자여야 합니다. “실수로 다른 리전에 버킷을 만들 수 없는 상태”를 만들어야 감사에 대응할 수 있습니다.

2. 키 주권 — CMEK, 그리고 EKM. 고객 관리 암호화 키(CMEK)는 기본이고, 더 높은 수위가 필요하면 Cloud EKM(External Key Manager)으로 암호화 키 자체를 국내의 외부 키 관리 시스템에 보관할 수 있습니다. 키가 국내에 있고 우리가 쥐고 있으면, 해외에서 데이터에 접근하려 해도 키 없이는 복호화가 불가능합니다. 여기에 Key Access Justifications를 붙이면 Google이 키를 사용하려는 사유를 건별로 확인하고 거부할 수 있습니다.

3. 접근 투명성과 접근 승인. Access Transparency는 Google 직원이 지원 목적 등으로 고객 데이터에 접근한 내역을 로그로 남기고, Access Approval은 그 접근을 사전 승인제로 바꿉니다. “CSP 직원이 우리 데이터에 접근할 수 있는가”라는 단골 감사 질문에 대한 기술적 답변입니다.

4. VPC Service Controls로 경계 설정. IAM이 뚫려도 데이터가 조직 경계 밖으로 나가지 못하게 하는 서비스 경계(perimeter)입니다. 특히 뒤에 나올 Vertex AI를 경계 안에 넣어서, AI API 호출 자체가 통제된 네트워크 안에서만 일어나도록 해야 합니다.


AI 영역에서 신경 쓸 것 — 핵심은 “LLM이 어디에서 도는가”

이제 본론입니다. 데이터 레지던시는 익숙한 주제지만, LLM 워크로드는 저장이 아니라 처리(processing)가 중심이라서 기존 체크리스트가 그대로 적용되지 않습니다.

1. Global endpoint를 쓰면 안 됩니다

Vertex AI에서 Gemini를 호출하는 방법은 크게 두 가지입니다.

  • Global endpoint — 가용성과 처리량을 우선해서, 요청을 전 세계 리전 중 여유 있는 곳으로 라우팅합니다. 프롬프트가 어느 나라에서 처리될지 보장되지 않습니다.
  • Regional endpoint — 지정한 리전 안에서 추론이 수행됩니다.

Global endpoint는 편하고 쿼터도 넉넉하지만, 규제 워크로드에서는 선택지가 아닙니다. 금융 데이터나 기술자료가 포함된 프롬프트가 어느 리전의 가속기에서 처리될지 모른다는 것은, 감사 관점에서 “국외 반출 여부를 알 수 없다”는 뜻이기 때문입니다. 규제 대상 워크로드는 반드시 regional endpoint를 쓰고, 원하는 모델이 해당 리전에서 서빙되는지를 확인해야 합니다.

여기서 현실적인 문제가 나옵니다. 모든 모델이 모든 리전에 있지 않습니다. 최신 모델일수록 미국·유럽 리전에 먼저 풀리고, 서울 리전 지원은 늦거나 일부 모델에 한정되는 경우가 많습니다. 그래서 프로젝트 초기에 “우리가 쓰려는 모델 버전이 asia-northeast3 regional endpoint에서 제공되는가”를 반드시 확인하고, 안 된다면 (1) 지원되는 이전 버전 모델을 쓰거나 (2) 규제 해석상 허용 가능한 리전을 법무·컴플라이언스와 협의하거나 (3) 아키텍처를 바꿔야 합니다. 이걸 PoC 끝나고 확인하면 프로젝트가 뒤집어집니다.

2. “저장 레지던시”와 “ML processing 레지던시”는 다른 계약입니다

Google Cloud의 데이터 레지던시 커밋은 기본적으로 저장 데이터(data at rest)에 대한 것입니다. Vertex AI에서는 여기에 더해 ML processing에 대한 레지던시 커밋이 별도로 존재하며, 지원되는 리전 목록도 다릅니다. 즉 다음 세 가지를 구분해서 확인해야 합니다.

  1. 프롬프트·튜닝 데이터·응답이 저장되는 위치
  2. 추론, 즉 ML processing이 수행되는 위치
  3. 전송 구간(in transit)의 경로

계약서와 서비스 약관에서 “data residency for ML processing”이 우리가 쓰는 리전에 적용되는지 확인하는 것이 실무 포인트입니다. 저장은 서울인데 처리는 다른 리전인 구성이 기술적으로 얼마든지 가능하기 때문입니다.

3. 프롬프트가 남는가 — 로깅, 캐싱, 학습 사용 여부

LLM 서비스에서 데이터가 새는 경로는 저장소가 아니라 부가 기능인 경우가 많습니다.

  • 어뷰즈 모니터링 캐싱 — Vertex AI는 남용 탐지를 위해 프롬프트를 짧은 기간 캐싱할 수 있습니다. 규제 워크로드라면 zero data retention 구성을 신청해서 캐싱을 끄는 것을 검토해야 합니다.
  • 요청/응답 로깅 — 운영 편의를 위해 켜는 로깅이 프롬프트 원문을 로그 저장소에 남깁니다. 로그 버킷의 리전과 보존 기간, 접근 권한까지 데이터 자산으로 관리해야 합니다.
  • 학습 사용 여부 — Google Cloud는 고객 데이터를 파운데이션 모델 학습에 사용하지 않는다는 것을 계약으로 확약합니다. 이것은 소비자용 Gemini 앱과 기업용 Vertex AI의 가장 큰 차이이며, 감사 대응 시 근거 문서로 챙겨둬야 하는 항목입니다.

4. Provisioned Throughput으로 리전을 고정

종량제(on-demand) 호출은 트래픽이 몰리면 리전 간 이동 유혹이 생기지만, Provisioned Throughput은 특정 리전의 처리 용량을 예약하는 방식이라 처리 위치 고정과 성능 보장을 동시에 얻습니다. 규제 워크로드가 프로덕션에 가면 사실상 필수 옵션이라고 봐야 합니다.

5. RAG 파이프라인은 전 구간의 리전 정합성을 봐야 합니다

LLM 엔드포인트만 서울로 고정하고 안심하면 안 됩니다. RAG 파이프라인은 구성 요소가 많습니다.

  • 임베딩 모델 — 임베딩 API 호출도 LLM 추론과 동일하게 처리 리전을 확인해야 합니다. 원문이 그대로 들어가는 호출입니다.
  • 벡터 저장소 — Vector Search 인덱스, 검색용 데이터 스토어의 리전.
  • Grounding with Google Search — 검색 그라운딩을 켜면 쿼리가 Google 검색 인프라로 나갑니다. 편리한 기능이지만 규제 데이터가 포함된 프롬프트에는 켜면 안 됩니다. 내부 데이터 그라운딩과 외부 검색 그라운딩을 워크로드 등급에 따라 분리해야 합니다.

파이프라인 다이어그램을 그려놓고 화살표마다 “이 데이터는 어느 리전을 지나는가”를 적어보는 것이 가장 확실한 점검 방법입니다.

6. 같은 Gemini라도 경로가 다르면 다른 제품입니다

Gemini 앱(소비자), Workspace의 Gemini, Vertex AI의 Gemini는 이름만 같지 데이터 처리 조건이 전부 다릅니다. 직원들이 브라우저에서 소비자용 Gemini에 업무 문서를 붙여넣는 순간 지금까지의 설계가 전부 무의미해집니다. 규제 데이터는 Vertex AI 경로만 허용하고, 나머지는 DLP와 프록시 정책으로 차단하는 운영 통제가 기술 설계만큼 중요합니다.

7. 최고 수위 — 모델을 데이터 옆으로 가져오기

리전 통제로도 부족한 국가핵심기술급 데이터라면 방향을 뒤집어야 합니다. 데이터를 모델에 보내는 게 아니라 모델을 데이터가 있는 곳으로 가져오는 것입니다.

  • Google Distributed Cloud air-gapped에서 Gemini 서빙 — 인터넷과 단절된 고객 시설 안에서 Gemini 모델을 운영하는 구성입니다. 프롬프트가 시설 밖으로 한 바이트도 나가지 않습니다.
  • 오픈 모델 자체 서빙 — Gemma 같은 오픈 모델을 GKE나 온프레미스 GPU에서 직접 서빙하면 모델 가중치까지 우리 손에 있으니 소프트웨어 소버린티 관점에서 가장 강한 구성입니다. 대신 모델 성능과 운영 부담은 감수해야 합니다.

그래서, Gemini LLM API는 소버린티를 만족하는가?

여기까지 읽었다면 자연스럽게 나오는 질문입니다. 답은 “어느 경로로 쓰느냐에 따라 다르고, 그마저도 지금은 시한부”입니다.

경로별 결론

호출 경로 소버린티 관점 결론
Gemini Developer API (AI Studio) 불만족. 요청이 전 세계 글로벌 풀에서 처리되는 구조이고, 처리 리전을 지정하는 기능 자체가 없습니다. 규제 워크로드에서는 검토 대상조차 아닙니다.
Vertex AI + global endpoint 불만족. Google 문서 스스로 “ML processing 요건이 있으면 global endpoint를 쓰지 말라”고 명시합니다. 어느 리전에서 처리될지 통제할 수도, 알 수도 없기 때문입니다.
Vertex AI + regional endpoint 조건부 만족. 서울 리전 지정 + ML processing 레지던시 커밋 + VPC-SC·CMEK 등 통제를 결합하면 처리 위치까지 입증 가능한 유일한 Gemini API 경로입니다.

즉 “Gemini API가 소버린티를 만족하는가”라는 질문의 실질적 답은 “Vertex AI regional endpoint에서 서빙되는 모델을 쓰는 동안만 그렇다”입니다. 그리고 바로 여기에 시한 문제가 있습니다.

2026년 10월 16일 — 시한부 선고

현재 regional endpoint에서 처리 위치를 고정할 수 있는 모델은 사실상 Gemini 2.5 세대(2.5 Pro / 2.5 Flash / 2.5 Flash-Lite)입니다. 그런데 이 세 모델은 Vertex AI에서 2026년 10월 16일 선셋(sunset, 서비스 종료) 이 예고되어 있습니다. 은퇴 한 달 전부터 온라인 추론·배치 추론·튜닝의 신규 접근이 차단되고, 은퇴일 이후에는 해당 모델 ID를 호출하면 404가 반환됩니다.

문제는 후속 세대입니다. Gemini 3.x는 (특히 Pro급 모델은) global endpoint 전용으로 출시되고 있습니다. regional endpoint로 호출하면 모델을 찾을 수 없다는 에러가 돌아옵니다. 앞서 본 대로 global endpoint는 처리 리전을 보장하지 않으므로, 이 구성은 규제 워크로드에서 쓸 수 없습니다.

두 사실을 겹치면 결론이 나옵니다. 선셋 시점까지 Gemini 3.x의 서울 리전 regional 서빙과 ML processing 레지던시 커밋이 열리지 않으면, 2.5가 내려가는 순간 “리전을 고정해서 소버린티를 만족하는 Gemini API”라는 선택지 자체가 사라집니다. 남는 방법은 클라우드 API가 아니라 GDC air-gapped에서 Gemini를 서빙하거나 오픈 모델을 자체 서빙하는 것뿐인데, 이것은 엔드포인트 교체가 아니라 아키텍처 교체입니다. 규제 심사를 다시 받는 수준의 변화입니다.

단서 하나: Google은 10월 16일을 “가장 이른(no earlier than) 은퇴일”로 공지했고, Gemini 3 GA 이후 최소 6개월 예고와 함께 확정 일자를 정하겠다고 밝혔습니다. 연기될 수는 있지만, 연기는 유예일 뿐 구조적 해법이 아닙니다.

지금 해야 할 일

  1. 2.5 기반 규제 워크로드의 마이그레이션 플랜을 지금 세우세요. 모델 교체는 엔드포인트 문자열 수정이 아닙니다. 프롬프트 호환성, 출력 품질, SDK 전환(구 Vertex AI SDK → Google Gen AI SDK) 검증에 수개월이 걸립니다.
  2. Gemini 3.x의 서울 리전 서빙·레지던시 커밋 로드맵을 어카운트 팀에 공식 확인하세요. 구두 답변이 아니라 계약·문서 근거로 받아야 감사에 쓸 수 있습니다.
  3. 열리지 않는 시나리오의 plan B를 미리 견적 내세요. GDC 또는 오픈 모델 자체 서빙으로 전환하는 비용·기간을 알아야, 선셋 일정에 끌려다니지 않고 협상할 수 있습니다.

시나리오별 권장 구성

지금까지의 내용을 세 가지 대표 시나리오로 매핑하면 이렇습니다.

시나리오 데이터 등급 권장 구성
금융 고객상담 챗봇 (가명처리 데이터) 규제 대상, 중요도 중 서울 리전 regional endpoint + VPC-SC + CMEK + 요청 로깅 통제 + 검색 그라운딩 차단
사내 문서 RAG (내부 중요정보) 규제 대상, 중요도 상 위 구성 + EKM(국내 키) + Access Approval + Provisioned Throughput + zero data retention
국가핵심기술 설계·공정 데이터 최고 수위 GDC air-gapped + Gemini on GDC 또는 오픈 모델 자체 서빙, 클라우드 API 호출 자체를 배제

마무리 — 소버린티는 리전 선택이 아니라 설계입니다

정리하면 이렇습니다.

  1. 용어를 구분하세요. 소버린티는 통제권이라는 목표이고, 소버린 클라우드는 수단입니다. “서울 리전 씁니다”는 소버린티의 일부일 뿐입니다.
  2. 데이터 기초 공사가 먼저입니다. 조직 정책으로 강제된 레지던시, 국내 보관 키, 접근 투명성, 서비스 경계 — 이 네 가지 없이 AI 소버린티는 없습니다.
  3. AI에서는 저장이 아니라 처리 위치를 물으세요. Global endpoint 배제, regional endpoint의 모델 지원 확인, ML processing 레지던시 커밋 확인, 프롬프트 로깅·캐싱 통제, RAG 전 구간의 리전 정합성 — 이것이 LLM 시대의 소버린티 체크리스트입니다.
  4. 모델 수명주기도 소버린티 리스크입니다. 지금 regional endpoint를 만족하는 Gemini 2.5 세대는 2026년 10월 16일 선셋이 예고되어 있고, 후속 3.x는 global endpoint 전용입니다. 서울 리전 서빙이 열리지 않은 채 선셋이 오면 리전 고정 방식 자체가 사라지므로, 마이그레이션 플랜과 plan B를 미리 준비해야 합니다.
  5. 등급에 맞는 단계를 고르세요. 모든 것을 air-gapped로 몰지도, 국가핵심기술을 일반 구성에 올리지도 마세요. 데이터 분류가 아키텍처를 결정합니다.

모델 리전 지원, 레지던시 커밋 범위, 규제 해석은 계속 바뀝니다. 이 글의 프레임으로 질문 목록을 만들되, 개별 항목은 계약 시점의 최신 문서와 법무 검토로 확정하시기 바랍니다. 소버린티는 한 번 사면 끝나는 제품이 아니라, 데이터 분류에서 시작해서 엔드포인트 선택까지 이어지는 설계의 연속입니다.

Multi-LLM Lock-in과 Harness Engineering

“특정 LLM에 종속되면 안 된다.”

이 말은 맞습니다. 그래서 많은 기업들이 Multi-LLM 전략에 집착합니다. “에이전트에서 LLM 설정값만 바꾸면 그대로 쓸 수 있다”고 생각하죠.

하지만 현실에서 이를 실행해 본 분이라면 아실 겁니다. LLM을 바꾸는 순간, 에이전트의 행동 자체가 달라집니다. 같은 도구, 같은 프롬프트, 같은 파이프라인인데 결과가 완전히 다릅니다. Lock-in 방지는 API 엔드포인트를 바꾸는 문제가 아니라, 에이전트를 처음부터 다시 세팅하는 문제입니다.


Multi-LLM의 진짜 문제 “프롬프트는 이식되지 않는다”

많은 분들이 LLM을 API로 바라봅니다. “입력을 넣으면 출력이 나오는 함수”라고 생각하죠. 그래서 OpenAI 대신 Claude를 쓰고, Gemini로 바꾸면 되지 않느냐고 말합니다.

그런데 실제로 해보면 이런 일이 벌어집니다:

  • 같은 프롬프트, 다른 결과. GPT-4o에서 잘 동작하던 프롬프트가 Claude에서는 과도하게 cautious한 응답을 내놓고, Gemini에서는 구조가 완전히 달라집니다.
  • 컨텍스트 윈도우 전략이 달라집니다. 128K 토큰을 쓸 수 있는 모델과 200K를 쓸 수 있는 모델에서의 컨텍스트 설계는 완전히 다른 엔지니어링입니다.
  • System prompt에 대한 반응성이 다릅니다. 어떤 모델은 system prompt를 충실히 따르고, 어떤 모델은 user turn의 마지막 지시를 더 우선합니다.

결국 모델을 바꾸면 프롬프트 엔지니어링을 처음부터 다시 해야 합니다.


LLM을 바꾸면 에이전트가 달라진다

프롬프트 이식성은 시작일 뿐입니다. 진짜 문제는 에이전트 수준에서 드러납니다. 에이전트는 단순히 프롬프트를 실행하는 것이 아니라, LLM의 판단력에 의존해 자율적으로 행동을 결정합니다. LLM이 바뀌면 그 판단이 바뀌고, 에이전트의 행동 전체가 달라집니다.

LLM을 바꾸는 것은 엔진을 바꾸는 것이 아니라 운전자를 바꾸는 것에 가깝습니다. 같은 차, 같은 길이어도 운전 방식이 완전히 달라집니다.

구체적으로 어떤 일이 벌어지는지 보겠습니다:

  • Tool calling 패턴이 달라집니다. 같은 도구 목록을 줘도 모델마다 도구 선택 전략이 다릅니다. 어떤 모델은 도구를 적극적으로 호출하고, 어떤 모델은 자체 추론으로 해결하려 합니다. 도구를 호출하는 순서, 병렬 호출 여부, 파라미터 구성 방식까지 전부 달라집니다.
  • 판단 기준이 달라집니다. “충분한 정보를 얻었는가”, “사용자에게 추가 질문이 필요한가”, “이 작업을 중단해야 하는가” — 에이전트의 모든 분기점에서 모델마다 다른 판단을 내립니다. GPT-4o에서 한 번에 끝나던 작업이 Claude에서는 확인 질문을 3번 거치는 식입니다.
  • 오류 처리 방식이 달라집니다. 도구 호출이 실패했을 때 재시도할지, 대안 경로를 찾을지, 사용자에게 보고할지 — 이 전략이 모델마다 다릅니다. 한 모델에서 안정적이던 에이전트가 다른 모델에서는 무한 재시도 루프에 빠질 수 있습니다.
  • 멀티스텝 추론 경로가 달라집니다. 같은 목표를 줘도 모델마다 문제를 분해(decompose)하는 방식과 순서가 다릅니다. 에이전트의 전체 실행 흐름 — 몇 단계를 거치는지, 어떤 순서로 처리하는지 — 이 LLM에 따라 완전히 달라집니다.

결론적으로 에이전트에서 LLM만 교체하면 “같은 에이전트”가 아닙니다. 겉은 같아 보여도 행동이 다른, 사실상 새로운 에이전트입니다. 그래서 LLM을 바꾸면 결국 에이전트의 세팅을 처음부터 다시 해야 합니다.


Lock-in의 본질은 API가 아니라 “엔지니어링 투자”

LLM lock-in을 API 호환성의 문제로 보면 간단해 보입니다. OpenAI 호환 API를 쓰면 되니까요. 하지만 진짜 lock-in은 세 가지 층위에서 발생합니다:

1. Prompt Engineering Lock-in

수개월에 걸쳐 최적화한 프롬프트 체계. Few-shot 예시, chain-of-thought 구조, 출력 포맷 제어 — 이 모든 것이 특정 모델의 행동 패턴에 맞춰져 있습니다.

2. Context Engineering Lock-in

RAG 파이프라인에서 어떤 정보를 얼마나, 어떤 순서로 컨텍스트에 넣을지. 이 설계는 모델의 컨텍스트 윈도우 크기, 위치 편향(positional bias), 정보 검색 능력에 종속됩니다.

3. Harness Engineering Lock-in

에이전트의 도구 호출 방식, 오류 처리, 반복 루프 설계, 멀티턴 대화 관리 — 이런 “모델을 감싸는 시스템”이 특정 모델의 function calling 스펙, 응답 구조, latency 특성에 맞춰져 있습니다. 여기에는 눈에 잘 보이지 않는 세팅들이 포함됩니다: 도구 선택 우선순위, 재시도 횟수와 백오프 정책, “충분하다”고 판단하는 임계값, 안전 장치의 트리거 조건 등. 이 모든 세팅이 특정 LLM의 행동 특성에 맞춰 튜닝된 것입니다. LLM을 교체하면 이 세팅을 전부 재검증하고 재조정해야 하며, 이는 사실상 에이전트를 처음부터 다시 만드는 것에 가까운 비용을 발생시킵니다.

모델을 바꾸는 것은 API 엔드포인트를 바꾸는 것이 아닙니다. 이 세 층위의 엔지니어링을 모두 다시 하는 것입니다.


관점의 전환: Multi-LLM이 아니라 Multi-Agent

여기서 발상의 전환이 필요합니다.

“어떤 LLM이든 갈아끼울 수 있게 만들자”는 접근은 각 모델의 강점을 포기하는 것과 같습니다. 최소공배수 방식으로 프롬프트를 설계하면, 어떤 모델에서도 “그럭저럭” 동작하지만 어떤 모델에서도 “최적”이 되지 않습니다.

대신 이렇게 생각해야 합니다.

LLM의 강점을 살리는 에이전트를 설계하고, 이 에이전트들을 오케스트레이션하는 Harness를 만들자.

  • 복잡한 추론이 필요한 태스크 → Claude에 최적화된 에이전트
  • 코드 생성과 실행 → Gemini에 최적화된 에이전트
  • 빠른 분류와 라우팅 → 경량 모델에 최적화된 에이전트

이때 중요한 것은 개별 에이전트가 아니라 이들을 엮는 Harness Engineering입니다. 에이전트 간 통신 프로토콜, 상태 관리, 오류 전파, 관찰 가능성(observability) — 이것이 진정한 엔지니어링 과제입니다.

GLM-5를 무료로 사용하는 방법: Modal API + OpenClaw 설정 가이드

2026년 2월 11일, Z.ai에서 GLM-5를 공개했습니다. 745B 파라미터의 오픈소스 LLM으로, MIT 라이선스로 배포되어 상업적 활용까지 가능합니다. 더 좋은 소식은 Modal 플랫폼이 Z.ai와의 파트너십을 통해 2026년 4월 30일까지 GLM-5를 완전 무료로 제공하고 있다는 것입니다.

이 글에서는 Modal에서 API 토큰을 발급받고, OpenClaw에서 GLM-5를 사용할 수 있도록 설정하는 전체 과정을 정리합니다.

GLM-5는 어떤 모델인가

GLM-5의 핵심 특징은 다음과 같습니다.

항목 내용
파라미터 745B (7,450억 개)
아키텍처 Mixture-of-Experts (MoE)
양자화 FP8
컨텍스트 윈도우 192,000 토큰
라이선스 MIT
강점 장기 호라이존 작업, 시스템 엔지니어링, 코드 생성

MoE 아키텍처는 모든 파라미터를 항상 사용하는 것이 아니라, 작업에 따라 필요한 전문가(Expert)만 활성화하는 방식입니다. 코딩 작업에는 코딩 전문가를, 창작 작업에는 창작 전문가를 사용하여 효율적으로 추론합니다.

벤치마크에서는 Claude Opus 4.6이나 GPT-5.3 Codex 같은 최첨단 상용 모델과 대등한 결과를 보여주었으며, 특히 코드 생성, 복잡한 문제 해결, 장기 맥락 이해에서 뛰어난 성능을 보이고 있습니다.

다만 FP8 양자화 상태에서도 약 700GB의 저장 공간이 필요하기 때문에 로컬에서 직접 실행하는 것은 사실상 불가능합니다. 그래서 Modal 같은 클라우드 플랫폼을 통해 API로 사용하는 것이 현실적인 방법입니다.

Modal에서 GLM-5 무료 사용하기

Modal은 AI/ML 모델을 쉽게 배포하고 실행할 수 있는 클라우드 플랫폼입니다. GLM-5 공개 전에 Z.ai와 파트너십을 맺고 모델 최적화 작업을 진행했기 때문에, 일반 사용자도 간편하게 GLM-5를 사용할 수 있습니다.

무료 제공 조건은 다음과 같습니다.

  • 무료 기간: 2026년 4월 30일까지
  • API 형식: OpenAI 호환 (chat/completions)
  • 동시 요청: 1개 (개인 사용 위주)
  • 토큰 제한: 없음
  • 생성 속도: 초당 30~75 토큰

동시 요청이 1개로 제한되어 있으므로 프로덕션 환경에는 적합하지 않지만, 개인 개발이나 학습 목적으로는 충분합니다.

1단계: Modal 계정 생성

Modal 웹사이트에 접속하여 계정을 생성합니다. GitHub 계정으로 간편 로그인이 가능합니다.

2단계: GLM-5 API 토큰 발급

GLM-5 토큰 발급 페이지에서 API 토큰을 생성합니다.

토큰 생성 후 표시되는 정보는 다음과 같습니다.

항목
Base URL https://api.us-west-2.modal.direct/v1
Model ID zai-org/GLM-5-FP8
API 형식 OpenAI 호환 (chat/completions)

주의: API 토큰은 발급 후 다시 확인할 수 없습니다. 반드시 안전한 곳에 저장해 두세요.

3단계: 환경 변수에 API 토큰 저장

API 토큰을 환경 변수로 설정합니다. 설정 파일에 토큰을 직접 하드코딩하는 것은 보안상 권장되지 않습니다.

Linux/macOS (~/.bashrc 또는 ~/.zshrc에 추가):

export LLM_BACKEND_API_KEY="modal_research_xxxxx...your-token-here"

설정 후 source ~/.bashrc 또는 터미널을 재시작하면 적용됩니다.

Windows PowerShell:

$env:LLM_BACKEND_API_KEY="modal_research_xxxxx...your-token-here"

영구적으로 설정하려면 시스템 환경 변수에 등록하거나 PowerShell 프로필에 추가하세요.

토큰 동작 확인

curl로 간단히 테스트할 수 있습니다.

curl https://api.us-west-2.modal.direct/v1/chat/completions \
  -H "Authorization: Bearer $LLM_BACKEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zai-org/GLM-5-FP8",
    "messages": [{"role": "user", "content": "Hello, GLM-5!"}],
    "max_tokens": 100
  }'

응답이 정상적으로 오면 토큰이 올바르게 설정된 것입니다.

OpenClaw에서 GLM-5 설정하기

이전 글에서 GCP에 OpenClaw를 설치하는 방법을 다뤘습니다. 이미 OpenClaw가 설치되어 있다면 설정 파일만 수정하면 GLM-5를 바로 사용할 수 있습니다.

OpenClaw 설정 파일 위치

# Linux/macOS
~/.openclaw/openclaw.json

# Windows
C:\Users\{username}\.openclaw\openclaw.json

GLM-5 공급자 추가

openclaw.json 파일의 models 섹션에 Modal 공급자를 추가합니다.

{
  "models": {
    "mode": "merge",
    "providers": {
      "modal": {
        "baseUrl": "https://api.us-west-2.modal.direct/v1",
        "apiKey": "${LLM_BACKEND_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "zai-org/GLM-5-FP8",
            "name": "GLM-5",
            "reasoning": true,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 192000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}

각 항목의 의미는 다음과 같습니다.

  • mode: "merge" — 기존 공급자를 유지하면서 새 공급자를 추가합니다. 기존에 사용하던 Claude나 GPT 설정이 있다면 그대로 유지됩니다.
  • apiKey: "${LLM_BACKEND_API_KEY}" — 환경 변수에서 토큰을 읽어옵니다. 설정 파일에 토큰을 직접 넣지 않아도 됩니다.
  • api: "openai-completions" — Modal의 GLM-5 엔드포인트가 OpenAI API 호환이므로 이 형식을 사용합니다.
  • reasoning: true — GLM-5의 추론 능력을 활성화합니다.
  • cost — 모든 값이 0입니다. 무료 기간이므로 비용이 발생하지 않습니다.
  • contextWindow: 192000 — 192K 토큰의 긴 컨텍스트를 지원합니다.
  • maxTokens: 8192 — 한 번의 응답에서 생성할 수 있는 최대 토큰 수입니다.

설정 검증

설정을 저장한 후 OpenClaw를 재시작하고 상태를 확인합니다.

openclaw status
openclaw models list

모델 목록에 GLM-5가 표시되면 설정이 완료된 것입니다. OpenClaw 채팅 인터페이스에서 GLM-5 모델을 선택하여 사용할 수 있습니다.

다른 모델과 비교

OpenClaw에서 여러 모델을 전환하며 사용할 수 있으니, 작업 유형에 따라 적합한 모델을 선택하면 됩니다.

항목 GLM-5 Claude Opus 4.6 GPT-5.3 Codex DeepSeek-V3
파라미터 745B ~400B (추정) ~500B+ (추정) 685B
라이선스 MIT (오픈소스) 상용 상용 MIT (오픈소스)
강점 장기 작업, 시스템 엔지니어링 일반 대화, 분석 코드 생성 코딩, 수학, 추론
비용 무료 (4/30까지) 유료 유료 무료 API 제공
컨텍스트 192K 200K 128K 128K

장기 프로젝트에는 GLM-5의 긴 컨텍스트 윈도우와 장기 맥락 유지 능력이 유리합니다. 빠른 코드 생성에는 GPT-5.3 Codex나 DeepSeek-V3가, 일반적인 대화와 분석에는 Claude Opus 4.6이 적합합니다. 예산이 제한적이라면 GLM-5와 DeepSeek-V3의 무료 옵션을 먼저 테스트해 보세요.

마무리

GLM-5는 오픈소스 모델 중에서 코딩과 에이전트 작업에 최고 수준의 성능을 보여주고 있습니다. Modal이 4월 말까지 무료로 제공하고 있으니, 이 기회에 OpenClaw와 함께 사용해 보는 것을 추천합니다. OpenAI API 호환 엔드포인트를 제공하기 때문에 OpenClaw 외에도 OpenAI API를 지원하는 대부분의 도구에서 바로 사용할 수 있습니다.

다만 동시 요청이 1개로 제한되어 있으므로, 본격적인 프로덕션 환경에서는 Modal의 유료 플랜이나 직접 호스팅을 검토해야 합니다. 개인 에이전트 용도로 24시간 돌리는 수준이라면 현재 무료 티어로 충분합니다.

참고 자료: