Agentforge on Yarang's Tech Lair

NATS JetStream으로 멀티-LLM 분산 오케스트레이터 구축하기

Fri, 08 May 2026 21:57:11 +0900

1편에서는 Claude, ZAI, Codex, Gemini 네 가지 AI를 같은 태스크에 동시에 돌리면서 발견한 모델별 제한 사항을 다뤘다. 이번 편은 “어떻게 그게 가능하도록 만들었나”—시스템 설계와 구현 이야기다.

시스템 개요

AgentForge는 세 가지 요소로 이루어진다.

[태스크 발행자]
 │ NATS JetStream publish
 ▼
[NATS 브로커] ─── af.worker.{id}.inbox
 │ JetStream consume (워커별 독립 스트림)
 ▼
[워커 폴러] × N (poller.py × 18개)
 │ LLM CLI 실행 (claude / codex / gemini)
 ▼
[결과 반환] af.task.{task_id}.completed

발행자가 NATS에 태스크를 올리면, 각 워커가 독립적으로 구독하고 있다가 자신의 inbox로 들어온 메시지를 받아 LLM CLI를 실행한다. 결과는 완료 주제로 다시 publish된다.

왜 NATS JetStream인가

메시지 브로커 선택지는 여러 개였다: Redis Streams, Kafka, RabbitMQ, NATS JetStream.

NATS JetStream을 선택한 이유:

단일 바이너리 — 별도의 런타임 없이 nats-server 하나로 동작한다. Kafka의 ZooKeeper나 RabbitMQ의 Erlang/OTP 의존성이 없다.
내장 영속성 — JetStream은 NATS 위에 올라가는 스트리밍 레이어로, 메시지를 파일시스템에 저장한다. 워커가 재시작되어도 처리 안 된 태스크가 유실되지 않는다.
NKey 기반 인증 — 워커별로 독립된 Ed25519 keypair를 발급할 수 있다. 한 워커가 침해되어도 다른 워커의 자격증명은 유효하다.
경량 — 단일 서버에서 메모리 사용량 ~30MB. 18개 워커를 연결해도 브로커 부하가 거의 없다.

핵심: poller.py의 백엔드 어댑터

워커의 핵심은 poller.py다. 이 파일 하나가 NATS 구독, LLM CLI 실행, 결과 반환을 모두 담당한다.

LLM별 실행 방식이 다르기 때문에, 백엔드 어댑터 딕셔너리로 분리했다.

_BACKENDS: dict[str, dict] = {
 "claude": {
 "bin": os.environ.get("CLAUDE_BIN", "/usr/local/bin/claude"),
 "tools": os.environ.get("ALLOWED_TOOLS", "Read,Edit,Write,Glob,Grep"),
 "model": os.environ.get("CLAUDE_MODEL", ""),
 },
 "codex": {
 "bin": os.environ.get("CODEX_BIN", "/usr/bin/codex"),
 "model": os.environ.get("CODEX_MODEL", ""),
 "sandbox": os.environ.get("CODEX_SANDBOX", "read-only"),
 },
 "gemini_cli": {
 "bin": os.environ.get("GEMINI_BIN", "/usr/bin/gemini"),
 "model": os.environ.get("GEMINI_MODEL", ""),
 },
}

MODEL_BACKEND 환경변수로 어떤 LLM을 쓸지 결정한다. 덕분에 동일한 poller.py 코드로 18개 워커가 각자 다른 LLM을 실행한다.

Claude 백엔드

async def run_claude(instructions: str, task_id: str) -> tuple[int, str]:
 cfg = _BACKENDS["claude"]
 cmd = [cfg["bin"], "--print", "--allowedTools", cfg["tools"]]
 if cfg.get("model"):
 cmd += ["--model", cfg["model"]]
 proc = await asyncio.create_subprocess_exec(*cmd, stdin=PIPE, stdout=PIPE, stderr=PIPE)

--print 플래그가 핵심이다. Claude Code가 대화 모드가 아닌 비대화형 모드로 실행되어 stdout으로 결과를 반환하게 만든다.

ZAI 백엔드

ZAI는 Anthropic API 호환 엔드포인트를 제공하기 때문에 별도 백엔드가 없다. 환경변수 두 개로 라우팅을 바꾼다.

# /etc/agentforge/cc-zai-high-dev-01.env
ANTHROPIC_BASE_URL=<ZAI endpoint>
ANTHROPIC_AUTH_TOKEN=<ZAI API key>

systemd EnvironmentFile= 지시어로 이 파일을 주입하면, claude 바이너리가 ZAI 엔드포인트로 요청을 보낸다. 코드 변경 없이 환경변수만으로 다른 LLM 공급자를 연결하는 셈이다.

선언적 관리: fleet.yaml × servers.yaml

18개 워커를 수동으로 관리하는 건 비현실적이다. 두 개의 YAML 파일로 전체 인프라를 선언적으로 정의했다.

servers.yaml — 서버 인벤토리

servers:
 - name: worker-node-1
 role: worker-host
 services: [agentforge-worker, tunnel-arm1]

 - name: broker-host
 role: broker-host
 services: [nats-jetstream, postgres]

 - name: worker-node-2
 role: worker-host
 services: [agentforge-worker, tunnel-arm1]

fleet.yaml — 워커 배치

workers:
 - worker_id: cc-go-dev-01
 llm: claude-code
 model: claude-sonnet-4-6
 lang: go
 role: developer
 host: worker-node-1
 enabled: true
 create_pr: true

 - worker_id: codex-py-dev-01
 llm: codex
 model: gpt-5.5
 lang: python
 role: developer
 host: worker-node-1
 enabled: true
 create_pr: false

host 필드 하나를 바꾸면 워커가 다른 서버로 이동한다. enabled: false로 설정하면 배포 스크립트가 해당 워커를 중지한다.

워커 템플릿 시스템: provision_worker.py

워커를 새로 추가할 때마다 systemd 유닛 파일을 직접 작성하는 건 오류가 생기기 쉽다. Jinja2 템플릿 + 프로비저닝 스크립트로 자동화했다.

템플릿 구조

templates/
 systemd/
 claude.service.j2 # claude-code, ZAI 공용
 codex.service.j2 # OpenAI Codex
 gemini.service.j2 # Google Gemini CLI

claude.service.j2의 핵심 부분:

Environment=MODEL_BACKEND=claude
Environment=CLAUDE_BIN={{ claude_bin }}
{% if claude_model %}
Environment=CLAUDE_MODEL={{ claude_model }}
{% endif %}
{% if env_file %}
EnvironmentFile={{ env_file }}
{% endif %}
Environment=WORK_BASE={{ work_base }}
Environment=WORK_DIR={{ work_base }}/repo
Environment="{{ 'ALLOWED_TOOLS=' + allowed_tools }}"
Environment=CREATE_PR={{ 'true' if create_pr else 'false' }}
{% if create_pr and github_remote %}
Environment=GITHUB_REMOTE={{ github_remote }}
{% endif %}

ZAI 워커는 env_file 블록이 활성화되어 EnvironmentFile이 추가된다. PR 생성 워커는 github_remote가 주입된다. 나머지는 기본값을 쓴다.

provision_worker.py 사용법

# 미리보기 (실제 배포 없음)
python3 scripts/provision_worker.py --worker new-worker-id --dry-run

# 실제 배포 (NATS creds 발급 포함)
python3 scripts/provision_worker.py --worker new-worker-id --issue-creds

# fleet.yaml 전체 일괄 배포
python3 scripts/provision_worker.py --all

내부적으로 수행하는 작업:

fleet.yaml에서 워커 항목 읽기
servers.yaml에서 대상 호스트 읽기
Jinja2 템플릿 렌더링
SSH로 /etc/systemd/system/{worker_id}-poller.service 배포
워크 디렉터리 생성
systemctl daemon-reload && enable --now
(선택) nsc add user로 NATS NKey 발급 → creds 배포 → auth.conf 재생성

분산 호스트: 두 번째 서버에 워커 추가

모든 워커를 한 서버에서 돌리면 단일 장애점이 된다. 두 번째 호스트에 Claude 워커를 추가했다.

두 번째 호스트에서 NATS 브로커에 연결하는 방법은 autossh 터널이다.

[Unit]
Description=NATS 브로커 터널
After=network-online.target

[Service]
ExecStart=/usr/bin/autossh -N \
 -L 4222:127.0.0.1:4222 \
 -i /home/ubuntu/.ssh/id_ed25519 \
 broker-host
Restart=always
RestartSec=10

이 설정이 활성화된 상태에서 워커는 항상 nats://127.0.0.1:4222로 연결한다. 브로커 호스트 주소를 몰라도 된다. 터널만 살아있으면 어느 호스트에서든 동일하게 동작한다.

NATS 자격증명 운영 경험

구현 중 가장 복잡했던 부분은 NATS NKey 관리다.

NATS JetStream의 인증 구조는 계층적이다.

Operator (최상위 서명 기관)
 └── Account: SYS (시스템 계정)
 └── Account: Services (워커 계정)
 ├── User: cc-dev-01
 ├── User: cc-go-dev-01
 ├── User: codex-py-dev-01
 └── ...

각 워커는 독립된 User NKey를 가지고, Services 계정의 권한 범위(af.>, _INBOX.>, $JS.>) 내에서만 publish/subscribe할 수 있다.

신규 워커를 추가할 때 Operator의 signing key가 필요하다. 초기에 이 키의 백업을 만들지 않았다가 분실하는 사고가 있었다. 결과적으로 Operator를 전부 재생성하고 모든 워커의 creds를 일괄 교체했다. 서비스 다운타임은 약 60초.

# 재생성 절차
nsc add operator AgentForge
nsc add account SYS
nsc add account Services
for worker in cc-dev-01 cc-go-dev-01 ...; do
 nsc add user --account Services --name $worker \
 --allow-pub "af.>,_INBOX.>,$JS.>" \
 --allow-sub "af.>,_INBOX.>,$JS.>"
done
nsc generate config --mem-resolver --sys-account SYS > auth.new.conf

새 워커 추가: 전체 절차

이 시스템이 완성된 이후 새 워커를 추가하는 절차는 단순하다.

1단계: fleet.yaml에 항목 추가

- worker_id: my-new-worker
 llm: claude-code
 model: claude-haiku-4-5
 lang: multi
 role: developer
 host: worker-node-1
 enabled: true
 create_pr: false

2단계: 미리보기

python3 scripts/provision_worker.py --worker my-new-worker --dry-run

3단계: 실제 배포

python3 scripts/provision_worker.py --worker my-new-worker --issue-creds

끝이다. 템플릿 렌더링, SSH 배포, NATS 자격증명 발급, 서비스 등록까지 한 명령으로 처리된다.

다음 단계

현재 시스템은 워커가 태스크를 독립적으로 처리하는 구조다. 앞으로 만들고 싶은 것:

라우팅 정책: 태스크 특성에 따라 적합한 워커를 자동 선택 (Go 코드 → claude-go-dev, 비용 최우선 → ZAI 경량 티어)
결과 비교 대시보드: fan-out 결과를 나란히 보여주는 UI
비용 추적: 워커별 API 호출 비용 집계

코드는 GitHub에 공개되어 있다.

4개의 AI에게 같은 코딩 태스크를 동시에 보내봤다

Fri, 08 May 2026 21:55:39 +0900

같은 버그 수정 태스크를 Claude, ZAI(GLM), OpenAI Codex, Google Gemini에게 동시에 던지면 어떤 일이 벌어질까?

이 질문에서 AgentForge 프로젝트가 시작됐다. 여러 LLM CLI를 NATS JetStream 메시지 큐로 묶어서 같은 태스크를 병렬로 처리하는 시스템을 만들었고, 그 과정에서 예상치 못한 발견들이 있었다. 이번 글은 “설정하면서 뭘 발견했나"에 집중한 비교 실험 기록이다.

시스템의 설계·구현 이야기는 2편에서 다룬다.

테스트한 AI 목록

최종적으로 운영 중인 워커 18개의 구성은 다음과 같다.

계열	모델	비고
Claude Code	claude-sonnet-4-6	메인 개발 워커
Claude Code	claude-sonnet-4-5	이전 세대 비교용
Claude Code	claude-haiku-4-5	경량·고속
Claude Code	claude-opus-4-6	최고 사양
Claude Code	claude-opus-4-5	이전 세대 비교용
ZAI (GLM)	glm-5.1	고사양 티어
ZAI (GLM)	glm-4.7	중간 티어
ZAI (GLM)	glm-4.5-air	경량 티어
OpenAI Codex	gpt-5.5
Codex	gpt-5.4	1M 컨텍스트
Codex	gpt-5.4-mini	400K 컨텍스트
Codex	gpt-5.3-codex	272K 컨텍스트
Google Gemini	gemini-2.5-flash
Gemini	gemini-2.5-pro	고사양
Gemini	gemini-2.5-flash-lite	경량

처음 시작할 때 목록은 훨씬 짧았다. 어떤 모델을 쓸 수 있는지 직접 실험해보면서 늘어났다.

발견 1: Claude 3.x 시리즈는 이미 접근 불가

Claude Code를 오래 써온 사람이라면 Claude 3.7 Sonnet, 3.5 Sonnet, 3.5 Haiku를 떠올릴 수 있다. 그래서 이 모델들도 워커로 추가하려 했다.

claude --model claude-3-7-sonnet-20250219 --print "hello"
# → "may not exist or no access"

세 모델 모두 동일한 오류. Claude 3 시리즈는 2026년 초에 EOL을 맞이했고, Claude Code CLI를 통한 접근이 차단됐다. 현재 Claude Code 구독으로 쓸 수 있는 것은 4.x 계열뿐이다.

결론: Claude 워커는 4.5/4.6 계열로만 구성했다.

발견 2: ChatGPT 계정 Codex는 모델 선택이 제한적이다

OpenAI Codex CLI는 ChatGPT Plus/Pro 계정이나 별도 API 키로 인증한다. ChatGPT 계정 기반일 경우 접근 가능한 모델이 제한된다.

codex --model gpt-5.5-pro "fix the bug"
# → "Model gpt-5.5-pro is not supported with ChatGPT account"

codex --model gpt-5.5 "fix the bug"
# → 정상 작동

ChatGPT 계정으로 사용할 수 있는 모델:

모델	컨텍스트	추론 수준
gpt-5.5	1M / 1M	High
gpt-5.4	1M / 1M	Medium
gpt-5.4-mini	400K / 400K	Medium
gpt-5.3-codex	272K / 400K	Medium

gpt-5.5-pro를 포함한 다른 모델은 모두 “not supported with ChatGPT account” 오류를 반환한다. API 키 방식이라면 더 많은 모델을 쓸 수 있지만, 그건 다른 접근 방식이다.

발견 3: Gemini CLI는 2.5 시리즈만 된다

Gemini CLI(gemini 바이너리)로 여러 모델을 테스트했다.

gemini -p "hello" -m gemini-2.0-flash
# → ModelNotFoundError: models/gemini-2.0-flash is not found

gemini -p "hello" -m gemini-1.5-pro
# → ModelNotFoundError

gemini -p "hello" -m gemini-2.5-flash
# → 정상 작동

현재 계정으로 접근 가능한 Gemini 모델:

gemini-2.5-flash — 기본 추천 모델
gemini-2.5-pro — 고사양
gemini-2.5-flash-lite — 경량

Gemini 2.0 이하 버전은 ModelNotFoundError를 반환한다. 계정 플랜이나 API 키 종류에 따라 다를 수 있지만, Gemini CLI 기준으로는 2.5 시리즈만 안정적으로 동작했다.

발견 4: ZAI는 Claude SDK로 우회할 수 있다

ZAI는 Anthropic API와 호환되는 엔드포인트를 제공하는 서비스다. 덕분에 Claude Code CLI에서 환경변수 두 개만 바꿔서 GLM 모델을 쓸 수 있다.

ANTHROPIC_BASE_URL=https://<ZAI endpoint> \
ANTHROPIC_AUTH_TOKEN=<ZAI_KEY> \
claude --model glm-5.1 --print "fix the bug"

Claude Code가 내부적으로 Anthropic Python SDK를 쓰기 때문에, ANTHROPIC_BASE_URL만 오버라이드하면 동일한 포맷으로 ZAI의 GLM 모델을 호출한다. 별도의 어댑터 코드 없이 기존 claude 백엔드를 그대로 재사용할 수 있다는 점이 흥미로웠다.

사용한 GLM 모델 3종:

glm-5.1 — 고사양 티어
glm-4.7 — 비용·성능 균형점
glm-4.5-air — 경량·고속

4-way Fan-out 비교 테스트

18개 워커 중 대표 4개(Claude Sonnet, GLM-5.1, Codex gpt-5.5, Gemini 2.5 Flash)에 동일한 Go 버그 수정 태스크를 동시에 발행했다.

태스크: "fix the off-by-one error in the binary search function"

응답 시간 (wall clock):

워커	모델	응답 시간
cc-go-dev-01	claude-sonnet-4-6	~8초
cc-zai-high-dev-01	glm-5.1	~12초
codex-py-dev-01	gpt-5.5	~15초
gemini-py-dev-01	gemini-2.5-flash	~10초

응답 시간보다 흥미로운 건 접근 방식의 차이다. Claude는 함수 전체를 리팩토링하는 경향이 있었고, Gemini는 최소한의 수정을 선호했다. Codex는 테스트 코드까지 함께 추가하는 경우가 많았다.

물론 이건 단일 태스크 결과라 통계적 의미는 없다. 벤치마크가 아니라 “실제로 동작하는지 확인"하는 수준의 검증이었다.

분산 워커: 두 번째 호스트 추가

워커들이 모두 한 서버에 있으면 비교 실험의 의미가 약해진다. 그래서 두 번째 호스트에 Claude 워커를 추가했다.

두 번째 호스트에서 NATS 브로커(첫 번째 호스트)에 접근하는 방법은 autossh 터널이다.

[Service]
ExecStart=autossh -N -L 4222:127.0.0.1:4222 broker-host

로컬의 4222 포트를 브로커로 포워딩하면 워커 코드 변경 없이 어느 호스트에서나 nats://127.0.0.1:4222로 접속할 수 있다.

이 방식의 장점: 워커는 브로커가 어디 있는지 알 필요가 없다. 항상 localhost:4222로 연결하면 된다.

운영하면서 가장 당황했던 순간

가장 곤혹스러운 상황은 NATS operator signing key를 분실한 것이었다. NATS JetStream은 NKey 기반 인증을 쓰는데, 신규 워커의 credentials를 발급하려면 operator/account의 signing key(nsc seed)가 필요하다.

nsc add user --account Services --name new-worker
# → "signing key not found"

백업이 없었다. 결국 NATS operator를 통째로 재생성하고, 모든 워커의 credentials를 새 권한 트리로 교체하는 대규모 컷오버를 진행했다. 서비스 다운타임은 약 60초였다.

교훈: NATS operator seed는 생성 즉시 오프라인 백업을 만들어라. 분실하면 재생성 외에 방법이 없다.

정리

이번 실험에서 얻은 실용적인 결론:

Claude 3.x는 EOL - 2026년 기준 Claude Code CLI에서 접근 불가. 4.x만 쓸 것.
Codex ChatGPT 계정은 모델 4종만 - gpt-5.5, 5.4, 5.4-mini, 5.3-codex. Pro 모델은 별도 API 키 필요.
Gemini는 2.5 시리즈만 - CLI 기준 이전 버전 접근 불가.
ZAI는 Claude SDK 환경변수 오버라이드로 통합 가능 - 별도 어댑터 불필요.
NATS NKey는 반드시 백업 - signing key 분실 = 전체 재발급.

다음 편에서는 이 워커들이 어떻게 연결되는지, 시스템 설계와 구현을 다룬다.

[AgentForge] 블로그 자동화 서비스 전체 아키텍처 — AI 댓글, 번역, 포스트 생성까지

Tue, 05 May 2026 00:30:00 +0900

블로그를 운영하면서 가장 번거로운 작업 세 가지가 있습니다. 댓글에 답하기, 영문 번역 유지하기, 그리고 꾸준히 글 쓰기. AgentForge 프로젝트에서는 이 세 가지를 모두 AI 에이전트로 자동화했습니다.

이 글에서는 2개 서버에 걸쳐 동작하는 블로그 자동화 서비스의 전체 아키텍처를 정리합니다.

시스템 토폴로지

┌─────────────────────┐ HTTPS ┌─────────────────────┐
│ arm1 서버 │ ──────────────▶ │ ec1 서버 │
│ (에이전트 오퍼레이터) │ │ (블로그 호스팅) │
├─────────────────────┤ ├─────────────────────┤
│ blog-agent (:8081) │ │ Hugo (nginx) │
│ ├─ CommentHandler │ │ Blog API (:8000) │
│ ├─ TranslateHandler│ │ ├─ translator.py │
│ └─ PostGenerator │ │ ├─ blog_manager.py │
│ │ │ └─ git_handler.py │
│ NATS / PostgreSQL │ │ │
│ Prometheus / Grafana │ │ Git (yarang/blogs) │
└─────────────────────┘ └─────────────────────┘

서버	역할	핵심 서비스
arm1	에이전트 오퍼레이터	`blog-agent.service` — Flask + Scheduler + LLM Client
ec1	블로그 호스팅 + API	Hugo (nginx) + `blog-api.service` (FastAPI)

두 서버 간 통신은 HTTPS API 호출만 가능합니다. arm1에서 ec1로의 SSH 접속은 차단되어 있어, 모든 연동은 Blog API를 통해 이루어집니다.

arm1: 통합 블로그 에이전트

왜 통합했는가

초기에는 댓글 응답, 번역, 포스트 생성이 각각 독립 프로세스(3개 systemd 서비스)로 운영되었습니다. 문제는:

Claude Code CLI(--print) 호출 방식으로 응답 시간 9.7초, 디스크 688MB 소모
systemd 유닛 6개 관리 부담
프로세스 간 상태 공유 불가

이를 1개 프로세스로 통합하면서 직접 LLM API 호출로 전환했습니다. 결과:

지표	Before	After
응답 시간	9.7초	1.7초
디스크 사용	688MB	~50MB
systemd 유닛	6개	1개
프로세스	3개	1개

아키텍처

class BlogAgent:
 """1 프로세스 = Flask (webhook) + Scheduler (timer) + LLM Client"""
 
 def __init__(self):
 self.config = AgentConfig.from_credentials()
 self.llm = LLMClient(self.config) # ZAI glm-4.7
 self.api = BlogAPIClient(self.config) # ec1 Blog API
 
 # 핸들러
 self.comment = CommentHandler(self.llm, self.config)
 self.translate = TranslateHandler(self.api)
 self.post_gen = PostGenerator(self.llm, self.api)
 
 # 스케줄러
 self.scheduler = Scheduler()
 self.scheduler.every(hours=6, task=self.translate.check_and_sync)
 self.scheduler.daily_at(hour=9, task=self.post_gen.generate_and_publish)

모듈별 동작

1. CommentHandler — AI 댓글 응답

GitHub Discussions의 Webhook 이벤트를 수신하여 자동으로 AI 댓글을 생성합니다.

[사용자 댓글] → GitHub Webhook → arm1 Flask → CommentHandler
 → LLM 호출 (ZAI glm-4.7) → 답변 생성 → GitHub API로 댓글 게시

트리거: Webhook 이벤트 기반 (실시간)
필터링: 블로그 소유자 댓글, AI 생성 댓글은 건너뜀
보안: HMAC-SHA256 Webhook 시크릿 검증, Flask-Limiter 적용

2. TranslateHandler — 자동 번역 트리거

6시간마다 ec1의 Blog API에 번역 동기화를 요청합니다.

[Scheduler 6h] → TranslateHandler.check_and_sync()
 → POST /translate/sync → ec1 Blog API가 실제 번역 수행

arm1은 번역을 직접 수행하지 않고, ec1 API에 트리거만 보냅니다. 실제 번역 로직은 ec1의 translator.py에 있습니다.

3. PostGenerator — 자동 포스트 생성

매일 오전 9시에 기술 블로그 포스트를 자동 생성합니다.

[Scheduler 09:00 KST] → PostGenerator.generate_and_publish()
 → 기존 주제 수집 → RSS 트렌드 참조 → LLM으로 콘텐츠 생성
 → 중복 검사 → Blog API로 게시

중복 방지가 핵심입니다. difflib.SequenceMatcher로 새 제목과 최근 100개 기존 제목의 유사도를 비교합니다:

def _is_duplicate_title(self, new_title, existing_titles):
 """threshold 0.6 이상이면 중복으로 판정"""
 new_lower = new_title.lower().strip()
 for title in existing_titles[-100:]:
 ex_lower = title.lower().strip()
 ratio = difflib.SequenceMatcher(None, new_lower, ex_lower).ratio()
 if ratio >= 0.6:
 return True
 return False

ec1: Blog API 번역 시스템

Gemini로의 전환

초기에는 ZAI(glm-4.7)로 번역을 수행했으나, 치명적인 문제가 발생했습니다:

glm-4.7은 reasoning 모델로, max_tokens 예산을 reasoning_content(내부 사고 과정)에 먼저 소진합니다. max_tokens=256이면 reasoning에 256토큰을 모두 쓰고, 실제 content는 빈 문자열이 됩니다.

이로 인해 9개 영문 게시글의 제목이 빈 문자열로 번역되는 사고가 발생했습니다.

해결책: Gemini 2.5 Flash Lite로 교체.

항목	ZAI (이전)	Gemini (현재)
모델	glm-4.7 (reasoning)	gemini-2.5-flash-lite
번역 시간	~30초/포스트	~8초/포스트
비용	API 유료	무료 (1,500건/일)
빈 응답 문제	발생	없음

OpenAI-Compatible 엔드포인트

Gemini는 OpenAI 호환 API를 제공합니다. 기존 코드를 한 줄도 바꾸지 않고 base URL만 교체하면 됩니다:

LLM_BASE_URLS = {
 "GEMINI": "https://generativelanguage.googleapis.com/v1beta/openai",
 "ZAI": "https://api.z.ai/api/coding/paas/v4",
}

번역 매칭 로직

한국어↔영어 게시글 페어링은 날짜 접두사 매칭을 사용합니다:

ko: 2026-05-04-001-개발-생산성-17배-극대화-deepseek-v4와-...
en: 2026-05-04-001-개발-생산성-17배-극대화-deepseek-v4와-...
 ↑ 같은 접두사 = 같은 게시글

slug의 언어가 다를 수 있지만, YYYY-MM-DD-NNN 부분이 같으면 같은 게시글로 인식합니다. 이 방식의 전제 조건은 같은 날짜에 같은 번호가 2개 이상 존재하면 안 된다는 것입니다.

Title-in-Body 번역 기법

제목을 별도 API 호출로 번역하면 reasoning 모델에서 빈 결과가 나오는 문제가 있었습니다. 해결책은 제목을 본문 첫 줄에 포함시키는 것:

# 번역 요청 시
prompt = f"# {original_title}\n\n{original_body}"

# 번역 결과에서 제목 추출
if translated.lstrip().startswith("# "):
 lines = translated.lstrip().split("\n", 1)
 extracted_title = lines[0].lstrip("# ").strip()
 translated_body = lines[1].lstrip("\n")

하나의 API 호출로 제목과 본문을 동시에 번역하므로, 맥락이 보존되고 토큰도 절약됩니다.

LLM 전략: 역할별 모델 분리

하나의 LLM으로 모든 작업을 처리하지 않습니다. 작업 성격에 맞춰 모델을 분리했습니다.

작업	서버	모델	이유
댓글 AI 응답	arm1	ZAI glm-4.7	대화형, 한국어 품질 우수
포스트 생성	arm1	ZAI glm-4.7	긴 글 생성, 창의성 필요
번역 (ko→en)	ec1	Gemini Flash Lite	비추론형, 빠르고 무료

핵심 원칙: reasoning 모델은 번역에 쓰지 않는다. reasoning 모델은 내부 사고에 토큰을 소비하므로, 단순 변환 작업에는 비추론형 모델이 적합합니다.

모니터링과 운영

헬스체크 엔드포인트

# arm1 에이전트
curl http://arm1:8081/health
# → {"status":"healthy","agent":"blog-agent","scheduler_jobs":2,"uptime_sec":...}

curl http://arm1:8081/status
# → {"scheduler":[{"name":"auto-translate","last_run":...},{"name":"post-generator","last_run":"2026-05-04"}]}

# ec1 Blog API
curl https://blog.example.com/api/health
# → {"status":"healthy","version":"2.0.0"}

관찰 포인트

지표	정상 범위	알림 조건
arm1 uptime	>0	서비스 다운
scheduler_jobs	2	≠ 2
번역 동기화	ko=en 개수 일치	차이 발생
포스트 생성	매일 1건	24시간 이상 미생성

교훈과 운영 팁

1. Reasoning 모델의 함정

max_tokens가 reasoning과 content를 합산한다는 것을 문서에서 명시하지 않는 경우가 많습니다. 빈 응답이 나오면 finish_reason을 확인하세요 — "length"라면 토큰 예산 부족입니다.

2. OpenAI-Compatible 패턴의 가치

번역 제공자를 ZAI에서 Gemini로 바꿀 때 코드 변경이 base URL 1줄이었습니다. 처음부터 OpenAI-compatible 인터페이스로 추상화하면 LLM 교체 비용이 극적으로 줄어듭니다.

3. 날짜 접두사 매칭의 제약

YYYY-MM-DD-NNN 패턴에서 같은 날짜에 같은 번호가 2개 이상 존재하면 번역 매칭이 깨집니다. PostGenerator에서 새 게시글 생성 시 해당 날짜의 마지막 번호 + 1을 확인하는 로직이 필수입니다.

4. 통합 프로세스의 이점

3개 독립 서비스를 1개로 통합하면서 얻은 것:

상태 공유 (LLM 클라이언트, 설정, API 클라이언트를 한 번만 초기화)
배포 단순화 (systemd 유닛 1개)
디버깅 용이 (로그가 한 곳에 모임)

향후 계획

arm1 에이전트의 LLM도 Gemini로 통합 검토
댓글 품질 평가 파이프라인 (자동 생성 댓글의 적절성 모니터링)
번역 품질 자동 검증 (역번역 비교)
AgentForge 프레임워크를 통한 에이전트 간 협업 확대

블로그 자동화는 “완전 자동"이 아니라 “최소 개입"을 목표로 합니다. AI가 생성한 콘텐츠를 사람이 검토하고, 시스템이 이상 징후를 감지하면 운영자에게 알리는 구조가 안정적인 운영의 핵심입니다.