Let's be Developers

ClaudeCode 로컬 모델 사용법

창빵맨 — Wed, 25 Feb 2026 12:37:04 +0900

요즘 내 개발작업의 90%를 ClaudeCode가 하고 정말 다양한 걸 시도해볼 수가 있어서 새벽에도 계속 작업을 하다 보니 Hourly limit은 안 걸리는데 Weekly Limit이 거의 간당간당해서 매주 살 떨린다.
그래서 간단한 서브 작업들은 로컬 LLM을 이용해 보고자 가이드를 작성하였다.

오늘은 로컬에 Qwen3 Coder Next 모델을 vLLM을 이용하여 서빙한 뒤 Claude Code에 연결해서 사용해 볼 것이다.

ollama 등은 claude code에서 바로 사용할 수 있게 세팅해 주는 옵션 등이 있는데 vLLM은 뭐 따로 할 건 없고, 그냥 claude code를 실행할 때 몇 가지 설정만 수동으로 바꿔주면 된다.

Qwen3 Coder Next

MoE(Mixture of Experts) 구조로 총 80B 파라미터 중 활성 파라미터는 3B — 10~20배 큰 모델급 성능을 낸다고 한다
512개 전문가 중 10개만 활성화하는 구조 (Gated Attention + Gated DeltaNet + MoE 하이브리드)
최대 262K 토큰 컨텍스트 지원
Non-thinking 모드만 지원 (thinking 블록 생성 안 함)
도구 호출(tool calling) 특화 설계, Apache 2.0 라이선스

에이전트 용도로 만든 모델답게, 장시간 추론이나 복잡한 도구 호출, 실행 오류 복구 같은 agentic 작업에 초점을 맞췄다.

게다가 Unsloth에서 다양한 크기의 양자화버전을 만들어줬느데, 아래에서 보다시피 양자화를 했음에도 성능이 매우 좋은 것을 확인할 수 있다.

Qwen/Qwen3-Coder-Next가 원래 150GB 정도의 vram을 요구하는데, 아래 차트를 보면 3비트 양자화의 경우 기존대비 약 100GB 정도의 Vram을 덜 쓰면서 유사한 성능을 낼 수 있다고 한다;;;;

unsloth는 아래버전들에 대한 gguf 양자화 버전이랑 unsloth/Qwen3-Coder-Next-FP8-Dynamic이라는 버전도 출시했으니 다양하게 직접 사용해 보면 좋을 것 같다.

Qwen3-Coder - a unsloth Collection

The Qwen3-Coder models deliver SOTA advancements in agentic coding and code tasks. Includes Qwen3-Coder-Next.

huggingface.co

모델에 대한 설명은 여기까지 하고 이제 실제로 ClaudeCode에 연결을 해보자

vLLM 서빙

우선 당연하게도 Ollama 혹은 vLLM을 이용하여 로컬에 모델을 띄워놔야 한다.

Requirements

GPU: FP8 양자화 기준 약 46GB VRAM 필요 (Qwen3-Coder-Next 기준)
vllm >= 0.15.0 (Qwen3-Coder-Next 지원 버전)
Python 환경

Installation

uv venv
source .venv/bin/activate
uv pip install -U vllm --torch-backend auto

vLLM 서버 시작

나는 단일 GPU 환경이라 작은 모델 기준으로 설명하겠지만, 기본 구조는 동일하다.

vllm serve Qwen/Qwen3-Coder-Next \
  --port 8000 \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_coder

여기서 중요한 옵션이 두 개다.

--enable-auto-tool-choice: 도구 호출 자동 감지 활성화
--tool-call-parser qwen3_coder: Qwen3 Coder 전용 파서 사용

서버가 뜨면 http://localhost:8000으로 OpenAI 호환 API가 열린다.

Claude Code 연결

서버가 떴으면 이제 Claude Code가 Anthropic 대신 로컬 서버를 바라보도록 설정해야 한다. 방법은 단순하다.

환경변수 설정

export ANTHROPIC_BASE_URL="http://localhost:8000"
export ANTHROPIC_API_KEY="sk-no-key-required"

ANTHROPIC_API_KEY는 인증용인데, 로컬 서버니까 뭘 넣어도 상관없다. 그냥 빈 값이 아닌 아무 문자열이면 된다.

영구적으로 적용하려면 ~/.zshrc 또는 ~/.bashrc에 추가하면 된다.

# ~/.zshrc
export ANTHROPIC_BASE_URL="http://localhost:8000"
export ANTHROPIC_API_KEY="sk-no-key-required"

모델 지정해서 실행

claude --model Qwen/Qwen3-Coder-Next

모델 이름은 vLLM에 서빙한 모델 ID와 일치해야 한다.

연결 확인

설정이 제대로 됐는지 간단하게 테스트해 볼 수 있다.

curl http://localhost:8000/v1/models

서빙 중인 모델 목록이 나오면 서버는 정상이다. 이후 claude 커맨드를 실행했을 때 응답이 오면 연결 성공이다.

혹시나 위 방법으로 적용했는데도, 계속 ClaudeCode에서 연결하라는 창만 뜬다면 아래 방법을 시도해 보면 된다. 차이점은 모델 기본값들을 방금 서빙한 모델들로 전부 설정해 주는 것이다.
(나는 ClaudeCode 구독을 안 한 상태에서 시도해서 이 방법으로 하니 성공했다)

ANTHROPIC_BASE_URL=http://localhost:8000 \
ANTHROPIC_API_KEY=dummy \
ANTHROPIC_AUTH_TOKEN=dummy \
ANTHROPIC_DEFAULT_OPUS_MODEL=my-model \
ANTHROPIC_DEFAULT_SONNET_MODEL=my-model \
ANTHROPIC_DEFAULT_HAIKU_MODEL=my-model \
claude

실제 사용 경험

솔직히 처음에는 "제대로 될까?" 반신반의했다. Claude Code는 tool calling을 정말 많이 쓰는 도구인데, 오픈소스 모델이 이걸 얼마나 잘 따라올지 확신이 없었다.

결론부터 말하면, 생각보다 잘 된다. 파일 편집, 터미널 명령 실행, 코드 검색 같은 기본적인 작업은 무리 없이 처리한다.
Anthropic Claude와 비교했을 때 복잡한 추론이나 긴 컨텍스트 처리에서는 차이가 느껴지긴 한다. 하지만 일상적인 코딩 작업, 예를 들어 함수 수정하거나 버그 찾거나 리팩토링하는 수준에서는 충분히 쓸 만하다.

References

Ubuntu 워크스페이스에서 앱이 다른 화면으로 이동하는 문제

창빵맨 — Mon, 23 Feb 2026 10:39:06 +0900

문제

Ubuntu 가상 데스크톱(워크스페이스)을 여러 개 사용할 때, 어떤 앱들은 각 워크스페이스마다 독립적으로 열 수 있는데,

특정 앱들은 새 워크스페이스에서 실행하면 현재 워크스페이스에 새 창이 뜨지 않고 기존에 그 앱이 열려있는 워크스페이스로 포커스가 이동해 버리는 현상이 발생했다.

원인

앱마다 동작 방식이 다르다.

매번 독립 실행되는 앱 (터미널 등)은 실행할 때마다 완전히 새로운 프로세스를 생성한다. 그래서 어느 워크스페이스에서 열든 그 자리에 독립적으로 뜬다.

Single Instance Application은 이미 실행 중인 인스턴스가 있으면 새 프로세스를 띄우지 않고, 기존 프로세스에 "창 하나 더 열어줘"라는 신호(D-Bus, 소켓 등)를 보낸다. 그러면 기존 인스턴스가 있는 워크스페이스에서 창이 열리게 된다.

Electron 기반 앱(Termius, Slack, Discord, VSCode 등)이나 일부 GTK 앱들이 이 방식을 사용하는 경우가 많다.

해결 방법

앱마다 방법이 다르고, 아예 막혀있는 경우도 있다.

1. `--new-window` 플래그 (가장 범용적)

Electron 앱과 Chromium 계열 브라우저 대부분에서 동작한다.

/path/to/app --new-window

예시:

/opt/Termius/termius-app --new-window
google-chrome --new-window
code --new-window

2. `--no-single-instance` 플래그

일부 앱에서 싱글 인스턴스 제한 자체를 비활성화할 수 있다.

/path/to/app --no-single-instance

3. 앱 자체 실행 경로 확인

which 또는 find로 실제 바이너리 경로를 먼저 확인한다. PATH에 등록 안 된 앱은 전체 경로로 실행해야 한다.

which 앱이름
find /opt /usr/bin /usr/local/bin ~/.local -name "*앱이름*" 2>/dev/null

또는 .desktop 파일의 Exec= 라인에서 실제 경로를 확인:

cat /usr/share/applications/앱이름.desktop

앱 아이콘(런처)에 영구 적용하기

매번 터미널에서 플래그를 붙여 실행하기 번거로우면 .desktop 파일을 수정한다.

sudo nano /usr/share/applications/앱이름.desktop

파일 안의 Exec= 라인을 찾아 플래그 추가:

# 변경 전
Exec=/opt/앱/실행파일

# 변경 후(-> Exec=/opt/Termius/termius-app --new-window)
Exec=/opt/앱/실행파일 --new-window

저장: Ctrl+O → Enter → Ctrl+X

시스템 전체에 적용되는 /usr/share/applications/ 대신 사용자 전용으로 적용하려면 ~/.local/share/applications/에 복사해서 수정하면 된다.

안 되는 경우

위 방법이 모두 안 된다면, 앱이 싱글 인스턴스를 강하게 고정해놓은 것이다. 이 경우 대안:

GNOME 설정으로 창 고정: 창 타이틀바 우클릭 → "항상 이 워크스페이스에"
Auto Move Windows (GNOME Extension): 앱 실행 시 항상 지정한 워크스페이스로 자동 이동

주요 앱별 정리

앱	동작 방식	해결 플래그
Termius	Single Instance (Electron)	`--new-window`
Google Chrome	Single Instance	`--new-window`
VSCode	Single Instance (Electron)	`--new-window`
Slack	Single Instance (Electron)	`--new-window`
Discord	Single Instance (Electron)	보통 안 됨
gnome-terminal	독립 실행	불필요

BOJ Mate 개발기

창빵맨 — Fri, 20 Feb 2026 13:48:19 +0900

얼마전부터 친구랑 코테 공부를 시작해서 백준 온라인 저지(BOJ)를 열심히 풀고 있는데,
매번 똑같은 작업을 반복하다 보니까 슬슬 귀찮아졌다.
게다가 맥북 화면도 작은데 문제 보고 , 파일 만들고, 템플릿 복붙하고, 테스트 케이스 복사해서 입력 파일 만들고... 이런 걸 자동화 할 방법이 없을까 고민하던 차에, 직접 VS Code 익스텐션을 만들어버렸다.

그렇게 탄생한 게 바로 BOJ Mate다. ClaudeCode를 이용하여 개발했고 VS Code Marketplace에 정식 등록까지 완료하였다!

Intro

BOJ Mate는 백준 문제 풀이를 위한 올인원 VS Code 익스텐션이다.
문제 검색부터 코드 실행, 테스트, 제출, 심지어 AI 힌트까지 전부 VS Code 안에서 해결할 수 있다.

처음에는 단순히 "문제 번호 입력하면 파일 자동 생성되면 좋겠다" 정도로 시작했는데,
점점 욕심이 생기면서 기능이 추가되다 보니 꽤 쓸만한 도구가 나왔다.

Features

문제 관리가 자동화된다

가장 기본이 되는 기능이다. 문제 번호만 입력하면:

백준에서 자동으로 문제 정보를 가져온다 (난이도, 태그까지!)
문제별로 폴더/파일을 자동 생성한다
언어별 템플릿을 자동으로 적용한다
예제 입출력을 자동으로 저장한다

더 이상 문제 사이트 들어가서 예제 복붙할 필요가 없다는 거다. 이것만 해도 시간이 꽤 절약된다.

⚡ 테스트 실행이 한 번에

코드 짜고 나서 테스트하는 것도 정말 귀찮은 작업 중 하나다. 터미널 열고, 입력 파일 만들고, 리다이렉션으로 실행하고... 이제 그런 거 안 해도 된다.

Ctrl+Shift+T 한 번이면 저장된 테스트 케이스로 자동 검증
여러 테스트 케이스를 한 번에 돌릴 수 있다
통과/실패가 한눈에 보인다

실제로 써보니까 이게 진짜 편하더라. 코딩하고 바로바로 테스트할 수 있으니까 디버깅 속도가 훨씬 빨라졌다.

코드 제출도 VS Code 안에서

문제 다 풀었으면 이제 제출해야 하는데, 이것도 자동화했다.

쿠키 기반 자동 로그인
코드 제출을 VS Code에서 바로
GitHub 푸시도 커스텀 커밋 메시지 템플릿으로 한 번에

백준 사이트 들어가서 로그인하고, 파일 찾아서 복붙하는 과정이 사라진다. 코딩에만 집중할 수 있다는 게 이 익스텐션의 가장 큰 장점인 것 같다.

AI 힌트 - 막힐 때 도움받기

이건 좀 실험적으로 추가한 기능인데, 생각보다 유용하더라.

알고리즘 분류: "이 문제 어떤 알고리즘으로 풀어야 하지?" 싶을 때 힌트를 받을 수 있다.

단계별 힌트: 바로 답을 보는 게 아니라 단계별로 풀이 방향을 안내받는다.

전체 풀이: 정말 모르겠으면 완전한 풀이와 코드도 제공한다.

OpenAI, Anthropic, Google, Ollama까지 다양한 AI 프로바이더를 지원한다.
로컬 모델(Ollama)도 쓸 수 있어서 API 비용 걱정 없이 사용할 수도 있다.

⏱️ 통계와 타이머

문제 풀이 시간을 측정하고 싶은 사람들을 위해 타이머 기능도 넣었다.

문제별 풀이 시간 자동 측정
난이도별 통계
최근 풀이 기록

나중에 어떤 유형의 문제가 약한지 파악하는 데 도움이 된다.

어떤 언어를 지원하나?

백준에서 많이 쓰는 언어들은 대부분 지원한다:

언어	지원 버전
C++	C++17
Python	Python 3
Java	Java 11
JavaScript	Node.js
Rust	Rust 2021

각 언어마다 기본 템플릿을 제공하고, 물론 커스터마이징도 가능하다.

Installation

이제 VS Code Marketplace에 정식 등록되어서 설치가 진짜 쉬워졌다.

방법 1: VS Code Marketplace에서 설치

VS Code에서 Extensions (Ctrl+Shift+X) 열기
"BOJ Mate" 검색
Install 클릭

또는 VS Code Marketplace 페이지에서 바로 설치 가능하다.

방법 2: VSIX 파일로 설치

GitHub Releases에서 .vsix 파일을 다운받아서 설치할 수도 있다:

code --install-extension boj-mate-0.0.1.vsix

사용법은?

설치하고 나면 기본 설정만 해주면 된다

익스텐션 아이콘을 클릭하면 나오는 버튼을 통해서 설정을 진행해도 되고, 혹은 설정에서 해도ㅗ딘다.

{
  "bojmate.username": "your_boj_username",
  "bojmate.language": "py",
  "bojmate.workspacePath": "/path/to/problems"
}

AI 기능을 쓰고 싶으면 API 키도 설정해주면 된다:

{
  "bojmate.ai.enabled": true,
  "bojmate.ai.baseUrl": "https://api.openai.com/v1",
  "bojmate.ai.apiKey": "your_api_key",
  "bojmate.ai.hintLevel": "algorithm"
}

이후 사용법은 정말 간단하다:

사이드바에서 문제 번호 입력
"생성" 버튼 클릭
언어 선택
코딩 시작
Ctrl+Shift+T로 테스트
제출!

프로젝트 배경

이 프로젝트는 BOJ-extension이라는 익스텐션에서 영감을 받아 시작했다. 기존 익스텐션을 쓰다가 "이런 기능도 있으면 좋겠는데" 싶은 게 생겨서 직접 만들어보기로 했다.

처음에는 단순히 기능 추가 정도로 생각했는데, 점점 욕심이 생기면서 아예 완전히 새로운 아키텍처로 재작성하게 되었다. AI 힌트/피드백, 풀이 타이머, 통계, 코드 제출 기능 등이 추가되면서 꽤 다른 방향으로 진화했다.

주의사항

하나 중요한 점은, 이 익스텐션이 개인 학습 목적으로 만들어졌다는 거다. 백준 온라인 저지의 공식 제품이 아니고, 웹 스크래핑을 사용한다.

백준은 이용 규칙에서 웹 스크래핑을 금지하고 있는데, 과도한 트래픽을 방지하기 위해 24시간 캐싱을 적용했다. 그리고 백준 측에서 공식 API를 제공하면 바로 전환할 계획이다.

문제의 저작권은 해당 문제를 만든 사람에게 있으니, 문제 본문을 외부에 재배포하지 않도록 주의해야 한다.

오픈소스로

BOJ Mate는 MIT 라이선스로 공개되어 있다. 코드는 GitHub에서 확인할 수 있고, 이슈나 PR도 언제든 환영한다!

GitHub: https://github.com/Bae-ChangHyun/BOJ-Mate

GitHub - Bae-ChangHyun/BOJ-Mate

Contribute to Bae-ChangHyun/BOJ-Mate development by creating an account on GitHub.

github.com

VS Code Marketplace: https://marketplace.visualstudio.com/items?itemName=BaeChangHyun.boj-mate

BOJ Mate - Visual Studio Marketplace

Extension for Visual Studio Code - 백준 온라인 저지 문제 풀이를 위한 올인원 VS Code 익스텐션 - 문제 검색, 코드 실행, AI 힌트/피드백, 풀이 타이머, 통계, 코드 제출

marketplace.visualstudio.com

마무리

알고리즘 공부할 때 반복적인 작업 때문에 짜증났던 경험이 있다면, BOJ Mate 한번 써보길 추천한다. 문제 풀이에만 집중할 수 있게 도와주는 게 이 익스텐션의 목표다.

앞으로도 계속 개선해나갈 예정이니, 사용하다가 불편한 점이나 추가되면 좋을 기능이 있으면 GitHub Issues에 알려주면 좋겠다!

백준 문제 풀이, 이제 좀 더 편하게 해보자!

Cloudflare R2 가입 & 설정 가이드

창빵맨 — Thu, 5 Feb 2026 14:34:38 +0900

오늘은 쓰레드 자동화를 계획하던 도중, 쓰레드 글에 API를 이용하여 미디어(이미지, 동영상)을 첨부하기 위해서는 공개 접근 가능한 URL이 있어야 한다는 걸 알았다.

그래서 스토리지를 알아보던 도중 Cloudflare R2가 10GB까지 무료라고 하길래 이참에 써보기로 했다.

추가로 Egress(데이터전송)이 무료라서 나중에 옮기기도 쉬울 것 같았다.

Step 1: Cloudflare 계정 가입

dash.cloudflare.com/sign-up 접속
이메일 + 비밀번호로 가입 (무료)
이메일 인증 완료

[!tip] 신용카드 등록이 필요할 수 있지만, 무료 범위 내에서는 과금되지 않습니다.

Step 2: R2 버킷 생성

대시보드 왼쪽 메뉴에서 R2 Object Storage 클릭
Create bucket 클릭
버킷 이름 입력 (예: thread-media)
위치는 APAC 선택 (한국 가까운 리전)
Create bucket 완료

Step 3: 퍼블릭 액세스 설정

Threads API가 파일을 가져가려면 공개 URL이 필요합니다.

생성된 버킷 → Settings 탭
Public Development URL 활성화
pub-xxxxx.r2.dev 형태의 공개 도메인이 생성됨

이후 업로드한 파일은 https://pub-xxxxx.r2.dev/파일명으로 접근 가능합니다.

Step 4: API 토큰 생성

Python에서 업로드하려면 API 키가 필요합니다.

R2 Overview 페이지 → 우측 하단 Account Details의 Manage 클릭
Create Account API token 클릭
설정:
- Permission: Object Read & Write
- Specify bucket: thread-media (생성한 버킷)
Create API Token 클릭
표시되는 값 즉시 복사 (다시 볼 수 없음):
- Access Key ID → R2_ACCESS_KEY_ID
- Secret Access Key → R2_SECRET_ACCESS_KEY
- Endpoint → 버킷 상세 페이지에서 확인 (https://<ACCOUNT_ID>.r2.cloudflarestorage.com)

[!warning] API 토큰은 생성 직후에만 확인 가능합니다. 반드시 즉시 복사해 두세요.

Step 5: `.env`에 추가

R2_ACCESS_KEY_ID=your_access_key
R2_SECRET_ACCESS_KEY=your_secret_key
R2_ENDPOINT=https://<ACCOUNT_ID>.r2.cloudflarestorage.com
R2_BUCKET_NAME=thread-media
R2_PUBLIC_URL=https://pub-xxxxx.r2.dev

Step 6: Python으로 업로드 테스트

패키지 설치:

uv add boto3

업로드 코드:

import boto3

s3 = boto3.client('s3',
    endpoint_url='https://<ACCOUNT_ID>.r2.cloudflarestorage.com',
    aws_access_key_id='your_access_key',
    aws_secret_access_key='your_secret_key',
)

# 업로드
s3.upload_file('video.mp4', 'thread-media', 'media/video.mp4')

# 공개 URL
print('https://pub-xxxxx.r2.dev/media/video.mp4')

Claudian-옵시디언에서 Claude Code 사용하기

창빵맨 — Wed, 4 Feb 2026 17:04:46 +0900

회사에서 Claude Code를 결제해줘서 최근 유용하게 사용 중이다.
그러다 보니 예전부터 미뤄왔던 옵시디언 정리를 하고 싶다는 생각이 들었다. 개발 내용 문서화도 하고, 개인 정리도 하고 싶었는데 문제가 하나 있었다.

Claude Code와 옵시디언을 연동해주는 플러그인이 없더라.
그래서 어쩔 수 없이 옵시디언의 bash 플러그인을 이용해서 별도로 창을 띄워서 사용했었다. 솔직히 좀 불편했다. 설정도 귀찮고, 매번 창을 따로 열어야 하고...

그러던 중에 우연히 발견한 게 바로 Claudian이다!

Claudian

Claudian은 옵시디언 플러그인인데, Claude Code를 옵시디언 안에서 바로 사용할 수 있게 해준다. 쉽게 말해서 옵시디언 Vault가 Claude의 작업 디렉토리가 되는 것이다.

처음 봤을 때 "오, 이거다!" 싶었다. bash 플러그인으로 별도 창 띄우는 것보다 훨씬 간편하고 설정도 편해 보였다.

실제로 써보니까 꽤 괜찮은 기능들이 많다.

Features

파일 읽고 쓰기: Vault 안의 모든 파일을 읽고 쓸 수 있다. 에이전트처럼 알아서 동작한다.
이미지 분석: 드래그 앤 드롭이나 붙여넣기로 이미지를 넣으면 분석해준다. Vision API를 쓰는 것 같다.
인라인 편집: 노트 안에서 직접 텍스트를 수정할 수 있다. 단어 단위로 diff를 미리 보여줘서 뭐가 바뀌는지 확인 가능하다.
자동 컨텍스트: 현재 열려있는 노트를 자동으로 컨텍스트로 넣어준다.
@ 멘션: @ 문법으로 특정 파일만 선택적으로 포함시킬 수 있다.
태그 기반 제외: 민감한 노트는 태그로 제외시킬 수 있다.
에디터 선택 영역: 특정 부분만 하이라이트해서 컨텍스트로 쓸 수 있다.
외부 디렉토리 접근: Vault 밖의 파일도 접근 가능하다.
커스텀 인스트럭션: #으로 시작하면 시스템 프롬프트를 커스터마이즈할 수 있다.
슬래시 커맨드: /command 형태로 재사용 가능한 명령어를 만들 수 있다. 인자도 넣을 수 있다.
스킬 모듈: Claude Code의 스킬 아키텍처랑 호환된다.
MCP 서버 연결: Model Context Protocol 서버에 연결 가능하다.
모델 선택: Haiku, Sonnet, Opus 중에서 선택할 수 있다.
Plan 모드: 실행하기 전에 솔루션을 먼저 탐색해본다.

자세한건 직접 사용해보면서 습득하는게 빠른것 같다

Installation

설치 방법은 세 가지가 있다.

1. Release에서 직접 다운로드(추천)

GitHub Release에서 파일 세 개(main.js, manifest.json, styles.css)를 받아서 .obsidian/plugins/claudian/ 폴더에 넣고 설정에서 활성화하면 된다.

2. BRAT 사용

BRAT 플러그인을 설치하고 레포지토리 URL을 추가하면 자동으로 설치되고 업데이트도 관리해준다. 이게 제일 편한 것 같다.

3. 소스에서 빌드

개발자라면 직접 클론해서 빌드할 수도 있다.

# 플러그인 폴더로 클론
git clone https://github.com/YishenTu/claudian .obsidian/plugins/claudian
cd .obsidian/plugins/claudian

# 빌드
npm install
npm run build

Settings

설정 옵션이 꽤 다양하다.

사용자 이름 설정 (인사말용)
태그 기반 필터링
미디어 폴더 지정
커스텀 시스템 프롬프트
자동 스크롤 토글
대화 제목 자동 생성

모드	설명
YOLO	자동으로 모든 작업 승인 (위험할 수 있음)
Safe	매번 승인 필요 (권장)
Plan	실행 전에 계획 먼저 검토

그 외에도:

Bash 커맨드 블랙리스트 (정규식 지원)
Export 경로 제한 (기본: Desktop, Downloads)
사용자 Claude 설정 통합
커스텀 MCP 서버 설정
Claude Code 플러그인 관리
환경 변수 구성
CLI 경로 지정

보안 관련해서도 꽤 신경 쓴 것 같다.

Claude의 파일 접근은 Vault로 제한된다 (symlink 검증 포함)
외부 쓰기는 설정한 export 경로로만 가능하다
모든 설정과 상호작용은 vault/.claude/에 로컬 저장된다
세션 데이터는 ~/.claude/projects/에 저장된다
입력, 첨부 파일, 툴 출력은 API 제공자(기본 Anthropic)로 전송된다

Requirements

시작하기 전에 필요한 것들:

Claude Code CLI 설치 (네이티브 설치 추천)
Obsidian 1.8.9 이상
데스크톱 환경 (macOS, Linux, Windows)
Claude 구독 또는 Anthropic API 접근 권한

Summary

옵시디언 쓰면서 Claude Code도 쓰고 있다면 Claudian은 거의 필수 플러그인이라고 할 수 있다. 설치도 간단하고, 설정도 직관적이고, 기능도 강력하다.

특히 문서화 작업이나 개인 노트 정리할 때 AI 도움을 받고 싶다면 정말 추천한다. BRAT으로 설치하면 업데이트 관리도 자동으로 되니까 한번 써보길 바란다!

GitHub - YishenTu/claudian: An Obsidian plugin that embeds Claude Code as an AI collaborator in your vault

An Obsidian plugin that embeds Claude Code as an AI collaborator in your vault - YishenTu/claudian

github.com

Daggr - HuggingFace의 새로운 AI 워크플로우 도구

창빵맨 — Mon, 2 Feb 2026 09:45:21 +0900

오늘은 최근 HuggingFace에서 공개한 Daggr라는 도구에 대해서 알아보려 한다. 2026년 1월 29일에 공개된 따끈따끈한 신상인데, AI 파이프라인 구축할 때 겪는 여러 문제들을 해결할 수 있는 도구라고 한다.

Daggr가 뭐냐면

쉽게 말해, 여러 AI 모델이나 처리 단계를 연결해서 복잡한 워크플로우를 만드는 Python 라이브러리다.
Gradio 팀에서 만들었는데, Gradio 앱, ML 모델, 커스텀 함수를 블록처럼
조립할 수 있다.

예를 들어, "이미지 생성 → 배경 제거 → 3D 에셋 변환"이라는 10단계 파이프라인이 있다고 치자.
기존 방식으로는 중간에 뭔가 잘못되면 전체를 다시 돌려야 했는데, Daggr는 각 단계를 독립적으로 재실행하고 결과를 확인할 수 있다.

나는 처음에 "또 하나의 GUI 도구겠지" 싶었는데, 막상 보니 접근이 좀 달랐다.
코드로 정의하면 자동으로 비주얼 캔버스가 생성되는 식이다.
즉 코드 기반의 버전 관리도 되면서, 디버깅은 GUI로 편하게 할 수 있다는 것이다.

Background

AI 애플리케이션 개발할 때 겪는 문제가 있다.

기존 방식의 문제점

API 체이닝이 복잡하다
여러 모델을 연결할 때 관리가 어렵다. 어떤 모델이 어떤 입력을 받고 출력을 내는지 추적하기 힘들다.
디버깅이 비효율적이다
10단계 파이프라인에서 7번째 단계가 잘못됐는데, 전체를 다시 실행해야 한다니... 시간과 비용 낭비가 심하다.
중간 결과를 보기 어렵다
각 단계의 출력이 어떤지 확인하려면 별도로 코드를 짜거나 로그를 뒤져야 한다.
선택지가 극단적이다
- GUI 에디터: 시각적이지만 버전 관리 안 됨
- 무거운 오케스트레이션 플랫폼: 기능은 많은데 학습 곡선 가파름
- 순수 스크립트: 버전 관리는 되는데 디버깅 지옥

Daggr의 해결책

문제	Daggr의 접근
API 체이닝 복잡성	노드 기반 연결로 시각화
디버깅 비효율	각 노드별 독립 재실행 가능
중간 결과 추적	모든 노드 출력 자동 표시
버전 관리 vs GUI	코드 우선 + 자동 비주얼 캔버스

쉽게 말해, "Python 코드로 정의하면 알아서 GUI가 생기고, 각 단계별로 실행/검사할 수 있다"는 것이다.

핵심 기능들

1. 코드 기반 + 자동 시각화

Daggr의 가장 큰 특징은 이거다.

# 코드로 정의
image_gen = GradioNode(...)
bg_remover = GradioNode(...)
graph = Graph(nodes=[image_gen, bg_remover])
graph.launch()  # 자동으로 비주얼 캔버스 생성

이렇게 하면 자동으로 각 노드가 시각화되고, 연결 관계가 그려진다. Git으로 코드 관리도 되고, 디버깅은 GUI로 할 수 있다니 꽤 괜찮은 아이디어다.

2. 노드별 재실행

10단계 파이프라인에서 7번째 단계만 문제면? 그 단계만 다시 돌리면 된다. 이전 단계들의 결과는 캐시되어 있어서 시간 낭비가 없다.

심지어 "백업 노드"라는 게 있어서, 특정 모델이나 Space를 다른 걸로 교체해서 다시 실행할 수도 있다고 한다. A 모델로 했는데 결과가 별로면, B 모델로 바꿔서 해당 단계만 재실행하는 식이다.

3. Gradio 통합

Gradio 팀이 만들었으니 당연한데, Gradio Space를 그냥 갖다 쓸 수 있다. 어댑터나 래퍼 없이 Space 이름만 입력하면 끝이다.

node = GradioNode(
    "hf-applications/Z-Image-Turbo",
    api_name="/generate_image",
    inputs={"prompt": gr.Textbox(...)},
    outputs={"image": gr.Image(...)},
)

공개 Space든 비공개 Space든 참조 가능하고, 심지어 run_locally=True 옵션을 주면 Space를 로컬로 복제해서 격리된 가상환경에서 실행한다. 로컬 실행 실패하면 자동으로 원격 API로 폴백된다고 한다.

4. 상태 지속성 (State Persistence)

Daggr는 워크플로우 상태를 자동으로 저장한다.

입력값
캐시된 결과
캔버스 위치

즉, 작업하다가 브라우저 끄고 다시 켜도 이어서 할 수 있다는 얘기다. "Sheets"라는 기능도 있어서 동일한 앱 내에서 여러 워크스페이스를 유지할 수 있다고 한다.

지원하는 노드 타입

Daggr는 3가지 타입의 노드를 지원한다.

1️⃣ GradioNode - Gradio Space 또는 로컬 앱

# 원격 Space 호출
image_gen = GradioNode(
    "hf-applications/Z-Image-Turbo",
    api_name="/generate_image",
    inputs={
        "prompt": gr.Textbox(label="Prompt", value="A cheetah...", lines=3),
        "height": 1024,
        "width": 1024,
        "seed": random.random,
    },
    outputs={
        "image": gr.Image(label="Generated Image"),
    },
)

# 로컬 실행
bg_remover = GradioNode(
    "hf-applications/background-removal",
    api_name="/image",
    run_locally=True,  # Space를 로컬에 복제해서 실행
    inputs={"image": gr.Image(label="Input")},
    outputs={"final_image": gr.Image(label="Output")},
)

run_locally=True를 쓰면 Space가 자동으로 복제되고, 격리된 가상환경에서 앱이 실행된다. 실패하면 알아서 원격으로 전환된다.

2️⃣ FnNode - 커스텀 Python 함수

def downscale_image(image, scale: float = 0.25):
    pil_img = Image.open(image)
    w, h = pil_img.size
    new_w = int(w * scale)
    new_h = int(h * scale)
    resized = pil_img.resize((new_w, new_h), resample=Image.LANCZOS)
    return resized

downscaler = FnNode(
    downscale_image,
    name="Downscale image",
    inputs={
        "image": previous_node.output,  # 이전 노드 연결
        "scale": gr.Slider(minimum=0.25, maximum=0.75, value=0.25),
    },
    outputs={
        "image": gr.Image(label="Downscaled Image"),
    },
)

일반 Python 함수를 노드로 만들 수 있다. 데이터 전처리나 간단한 변환 작업에 유용하다.

3️⃣ InferenceNode - HuggingFace Inference Providers

flux_enhancer = InferenceNode(
    model="black-forest-labs/FLUX.2-klein-4B:fal-ai",  # model:provider 형식
    inputs={
        "image": downscaler.image,  # 이전 노드 출력 연결
        "prompt": gr.Textbox(label="Prompt", value="Transform this into 3D"),
    },
    outputs={
        "image": gr.Image(label="Enhanced Image"),
    },
)

HuggingFace Inference API를 바로 호출할 수 있다. model:provider 형식으로 지정하면 된다.

설치 및 실행

설치

pip install daggr
# 또는
uv pip install daggr

Python 3.10 이상이 필요하다.

배포

로컬 공유 링크:

graph.launch(share=True)  # 공개 URL 생성

HuggingFace Spaces 배포:

requirements.txt에 daggr 추가
Gradio SDK로 Space 생성
코드 푸시

⚠️ 주의: InferenceNode 사용 시 HuggingFace 세밀한 액세스 토큰(fine-grained token)으로 "Inference Providers 호출" 권한만 부여하는 게 안전하다.

현재 상태 및 주의사항

Daggr는 베타 버전이다. 즉 API가 변경될 수 있다는 얘기다.

주의할 점:

워크플로우 상태는 로컬에 저장되는데, 업데이트 중 데이터 손실 가능성이 있다고 한다.
아직 초기 단계라 버그나 예상치 못한 동작이 있을 수 있다.
피드백은 GitHub Issues로 보내면 된다.

예제 Space:

Daggr Image To 3d - a Hugging Face Space by merve

This app transforms your uploaded images into professional 3D-ready assets. First, it removes the background from your image, then enhances it with AI to create a clean 3D render. Finally, it gener...

huggingface.co

여기 들어가서 실제로 어떻게 동작하는지 확인해 볼 수 있다.

마무리

핵심 정리:

코드 기반 + 자동 시각화: 버전 관리와 직관성을 둘 다 잡음
노드별 재실행: 디버깅 효율성 대폭 향상
Gradio 통합: Space를 그냥 갖다 쓸 수 있음
상태 지속성: 작업 이어하기 가능

나는 아직 실제 프로젝트에 써본 건 아니지만, 프로토타이핑이나 빠른 실험에는 상당히 유용할 것 같다는 생각이 든다. 특히 여러 모델을 조합해서 뭔가 만들 때 기존 방식보다 훨씬 편할 것 같다.

다만 베타라서 프로덕션에 바로 쓰기는 좀 그렇고, 앞으로 어떻게 발전할지 지켜봐야 할 듯하다. 관심 있으면 한번 써보길 바란다!

참고 자료:

Microsoft VibeVoice-ASR

창빵맨 — Mon, 2 Feb 2026 09:32:36 +0900

최근 음성 인식 기술이 정말 빠르게 발전하고 있다는 걸 체감하는 요즘인데, 마이크로소프트가 또 하나 재미있는 걸 오픈소스로 공개했다고 한다.

바로 VibeVoice-ASR이라는 음성-텍스트 변환 모델이다.

오늘은 이 VibeVoice-ASR이 뭔지, 왜 주목할 만한지 정리해보려 한다.

VibeVoice-ASR

VibeVoice-ASR은 마이크로소프트가 2026년 1월 21일에 오픈소스로 공개한 자동 음성 인식(ASR) 모델이다. 쉽게 말해 음성 파일을 텍스트로 변환해 주는 AI인데, 기존 모델들과는 좀 다른 특징이 있다.

가장 눈에 띄는 건 60분짜리 음성을 통째로 한번에 처리할 수 있다는 점이다. 보통 ASR 모델들은 긴 음성을 짧게 잘라서 처리하는데, 이 녀석은 한 시간짜리를 그냥 한방에 받아서 처리한다.

VibeVoice-ASR은 단순히 음성을 텍스트로 변환하는 것뿐만 아니라 , 세 가지 정보를 한꺼번에 제공한다.

Who (누가): 화자 식별 - 누가 말했는지 구분
When (언제): 타임스탬프 - 몇 분 몇 초에 말했는지
What (무엇을): 실제 발화 내용 텍스트

즉, 회의 녹음 파일을 넣으면 "A씨가 3분 20초에 '이 프로젝트는 내일까지 완료해야 합니다'라고 말했다" 이런 식으로 구조화된 결과를 받을 수 있다는 것이다.

Features

1. 60-minute Single-Pass Processing

최근에 나오는 ASR 모델들을 보면, 짧게 짧게 끊어서 전사하는 경우가 많이 보였다.
나도 사실 어차피 음성을 텍스트로변환하기만 하면 되니까, 정확하기만 한다면 뭐 짧게 여려 번하던 길게 한 번에 하던 상관없다고 생각했다.
그러나 짧게짧게 변환하면 아래와 같은 문제가 발생한다.

화자 추적 일관성 문제: 앞 구간에서 "화자 1"로 인식됐던 사람이 뒷 구간에서 "화자 3"으로 바뀌는 일이 발생
맥락 손실: 대화 흐름이 끊겨서 문맥 이해가 어려움
처리 파이프라인 복잡도: ASR → 화자 분리 → 타임스탬프를 각각 돌려야 함

이를 VibeVOice-ASR은 64K 토큰 길이로 최대 60분을 한번에 받는다. 그래서:

한 시간 내내 같은 사람을 일관되게 추적 가능
전체 대화의 맥락을 유지하면서 인식
ASR + 화자분리 + 타임스탬프를 하나의 모델에서 동시에 처리

쉽게 말해 "전체 그림을 보면서 처리한다"는 것이다.

2-1. Customized Hotwords:

이게 실무적으로 진짜 유용할 것 같은데, 도메인 특화 단어를 미리 알려줄 수 있다.

예를 들어:

기업 회의: 프로젝트 이름, 임직원 이름
의료: 질병명, 약물명
법률: 전문 용어

이런 걸 "핫워드"로 등록하면 인식 정확도가 크게 올라간다고 한다. 일반 모델은 "갤럭시폴드"를 "갤럭시 폴트"로 잘못 인식할 수 있지만, 핫워드로 등록하면 정확하게 인식하는 식이다.

2-2. Multilingual & Code-Switching Support

다국어를 지원하는데, 여기서 재미있는 건 언어 설정을 따로 안 해도 된다는 것이다. 자동으로 감지한다.

더 신기한 건 코드 스위칭(Code-Switching) 지원이다.

이런 식으로 한국어-영어가 섞인 발화도 자연스럽게 인식한다. 실제로 우리가 말할 때 이렇게 섞어 쓰는 경우가 많으니 실용적이다.

가장 좋았던 것은 한국어를 지원하는 모델이라는 것이다 ㅜㅜ 감사합니다.

3. 모델 스펙

항목	내용
파라미터 수	9B (90억개)
데이터 타입	BF16 (Bfloat16)
포맷	Safetensors
라이선스	MIT
프레임워크	Transformers

MIT 라이선스라는 게 포인트다. 상업적으로도 자유롭게 사용 가능하다는 뜻이다.

논문도 공개되어 있다: arXiv:2601.18184

4. 성능

모델 평가에는 세 가지 지표를 사용한다고 한다:

DER (Diarization Error Rate): 화자 분리 오류율
cpWER (Character Piece Word Error Rate): 단어 인식 오류율
tcpWER (Time-aware cpWER): 시간 정보 고려한 오류율

정확한 수치 논문과 HuggingFace 페이지에 그래프로 나와있는데, gemini2.5 pro, gemini 3.0 pro와 비교하여 우수한 성능을 보였다

마무리

VibeVoice-ASR을 정리하면:

✅ 60분 통째로 한방에 처리 (ASR + 화자분리 + 타임스탬프 통합)
✅ 커스텀 핫워드로 도메인 특화 가능
✅ 50개 언어 + 코드 스위칭 지원
✅ MIT 라이선스로 상업적 사용 가능
⚠️ 실시간보다는 배치 처리에 적합

개인적으로는 회의 녹음 자동 정리용으로 진짜 유용할 것 같다. 특히 화자별로 발화 내용이 구분되는 건 엄청 편리할 듯하다.

다만 9B 모델이라 로컬에서 돌리려면 GPU가 필요하니, 간단한 테스트는 데모 페이지에서 해보고, 본격적으로 쓸 거면 클라우드 GPU 환경을 고려하는 게 좋겠다.

아무튼 마이크로소프트가 이런 고품질 모델을 오픈소스로 공개해 줘서 고맙다!! 나중에 실제 프로젝트에 적용해 보면 또 후기를 작성해 볼 예정이다.

허깅페이스에 데모도 공개되어있으니 실험해 보면 좋을 것 같다.

또한 Microsoft에서 작성한 파인튜닝 가이드도 존재하며, vllm으로 서빙도 가능해서 실무등에서 바로 활용해 볼 수 있을 것 같다.

가이드: Finetuning README
문서: vLLM-VibeVoice-ASR

Gradio

Click to try out the app!

dfd7cdd77aee79cc37.gradio.live

참고 자료

PaddleOCR-VL-1.5-초경량 OCR의 새로운 강자

창빵맨 — Mon, 2 Feb 2026 09:11:19 +0900

약 2-3개월 전부터 vlm을 이용한 OCR 모델들이 우르르 쏟아졌다. 그중에 Qwen 같은 대형 모델들도 있고 OCR에만 특화된 nanonet, dots.cor 등 소형 모델들도 다수 등장했다.
문서 파싱쪽 업무를 담당하면서 일주일에 10개씩 모델을 올렸다 내렸다 하고 있었는데 테스트 결과 정리하기도 이전에 새로운 모델이 또 출시됐다.

사실 이전 버전인 PaddleOCR-VL도 동일하게 0.9B에다가 벤치마크가 좋았어서 써봤었다.
성능은 기대만큼 괜찮았지만 아주 아주 약간의 아쉽지만 치명적인 부분들이 있었는데, 그런데 어제 마침 새로운 버전이 나왔다고 한다.

불과 0.9B 파라미터로 Gemini 3 Pro 같은 거대 모델들을 제치고 OCR 벤치마크 1위를 차지한 **PaddleOCR-VL-1.5가 그 주인공이다.

PaddleOCR-VL-1.5

바이두가 2026년 1월 29일에 공개한 초경량 비전-언어 모델(VLM)이다.
문서 인식(OCR)에 특화되어 있으면서도 크기는 겨우 0.9B 파라미터로 매우 대단하다.

핵심 구성 요소

컴포넌트	설명
비주얼 인코더	NaViT 스타일의 동적 해상도 처리
언어 모델	ERNIE-4.5-0.3B (바이두의 경량 LLM)
라이선스	Apache 2.0 (상업적 사용 가능!)
텐서 타입	BF16 (효율적 연산)

기본 베이스 모델은 ERNIE-4.5-0.3B이고, 여기에 NaViT 방식의 Vision Encoder을 붙여서 이미지 인식 능력을 극대화했다. 쉽게 말해서 가볍지만 똑똑한 구조라는 것이다.

놀라운 성능

이 모델의 진짜 충격적인 부분은 성능이다. OmniDocBench v1.5라는 벤치마크에서 94.5%의 정확도를 달성했다.

벤치마크를 보면 알겠지만 대형 모형들을 포함하여 최신 모델들을 모두 뛰어넘은 성능을 보여주고 있다.

하지만 요즘 벤치마크는 사실 믿기 어렵다는 게 사실이다. 데이터를 잘 만들고 오버피팅하면 되니까. 진짜 중요한 건 실제 환경에서 얼마나 잘 작동하느냐다.

PaddleOCR-VL-1.5는 "Real5-OmniDocBench"라는 실전 환경 테스트에서도 SOTA를 달성했다.

(Real5-OmniDocBench는 OmniDocBench v1.5 데이터셋을 기반으로 구축된, 실제 시나리오에 최적화된 새로운 벤치마크이다)

Real5 데이터셋은 다음 5가지 까다로운 시나리오를 테스트한다:

시나리오	설명	난이도
스캔	스캔 아티팩트, 노이즈 포함 문서	⭐⭐
기울어짐	비뚤어진 각도로 찍힌 사진	⭐⭐⭐
화면 촬영	모니터 화면을 카메라로 찍은 이미지 (반사 포함)	⭐⭐⭐⭐
조명	부분 조명, 그림자가 있는 문서	⭐⭐⭐
휘어짐	구겨진 종이, 곡면 변형	⭐⭐⭐⭐⭐

특히 휘어진 종이나 화면 촬영 같은 건 정말 어려운 케이스다.
일반 OCR로는 제대로 인식이 안 되는 경우가 많은데, PaddleOCR-VL-1.5는 이런 상황에서도 강력하게 작동한다고 한다.

개인적으로는 이 부분이 가장 마음에 든다. 실험실 데이터가 아니라 진짜 현실에서 마주칠 법한 상황을 잘 처리한다는 거니까.

최근 LLM, VLM들의 추세에 맞게 vllm을 통한 서빙도 바로 지원한다.

# vLLM 서버 시작 (Docker)
docker run \
    --rm \
    --gpus all \
    --network host \
    ccr-2vdh3abv-pub.cnc.bj.baidubce.com/paddlepaddle/paddleocr-genai-vllm-server:latest-nvidia-gpu \
    paddleocr genai_server --model_name PaddleOCR-VL-1.5-0.9B --host 0.0.0.0 --port 8080 --backend vllm

# CLI로 호출
paddleocr doc_parser \
    -i image.png \
    --vl_rec_backend vllm-server \
    --vl_rec_server_url http://127.0.0.1:8080/v1

단일 NVIDIA A100에서 배치 처리(512 문서)가 가능하다고 하니, 프로덕션 환경에서도 충분히 쓸만할 것 같다.

마무리: OCR의 새로운 기준

PaddleOCR-VL-1.5를 한 문장으로 정리하면 이렇다:

"0.9B 파라미터로 Gemini를 이긴, 실전에 강한 문서 파싱의 최강자"

AI 업계가 "더 크고 더 강한" 모델 경쟁에 집중할 때, 바이두는 반대로 "더 작고 더 효율적인" 방향을 택했다. 그리고 그 선택이 성공했다는 게 벤치마크로 증명되었다.

특히 인상적인 부분은:

✅ OmniDocBench v1.5에서 94.5% SOTA 달성
✅ Real5 벤치마크에서 실전 성능 입증
✅ Apache 2.0 라이선스로 상업적 활용 가능
✅ 109개 언어 지원으로 글로벌 확장성 확보

앞으로 문서 처리 자동화가 필요하다면 PaddleOCR-VL-1.5를 한번 고려해 보길 바란다. 특히 리소스가 제한된 환경이나, 빠른 추론 속도가 중요한 프로덕션 시나리오라면 거의 최선의 선택일 것 같다.

데모도 공개되어있으니 직접 서빙하기 귀찮은 사람은 테스트해보면 좋을 것 같다!

PaddleOCR-VL-1.5 Online Demo - a Hugging Face Space by PaddlePaddle

PaddleOCR-VL-1.5_Online_Demo

huggingface.co

참고 자료

HuggingFace 모델 페이지: https://huggingface.co/PaddlePaddle/PaddleOCR-VL-1.5
공식 문서: https://www.paddleocr.ai/latest/en/version3.x/pipeline_usage/PaddleOCR-VL.html
GitHub 저장소: https://github.com/PaddlePaddle/PaddleOCR
arXiv 논문: https://arxiv.org/abs/2601.21957
온라인 데모:

Sources:

Qwen3-ASR 오픈소스 음성 인식의 새로운 강자

창빵맨 — Fri, 30 Jan 2026 16:17:25 +0900

오늘은 어제 알리바바 클라우드의 Qwen 팀에서 공개한 Qwen3-ASR에 대해서 알아보려 한다.
2026년 1월 29일에 출시된 따끈따끈한 모델인데, 음성 인식(ASR) 분야에서 꽤 혁신적인 접근을 보여주고 있어서 정리해 봤다.

Qwen3-ASR은 알리바바 클라우드의 Qwen 팀이 만든 오픈소스 자동 음성 인식(ASR) 모델이다.
단순히 음성을 텍스트로 바꾸는 데서 그치지 않고, 언어 식별부터 타임스탬프 예측까지 한 번에 처리할 수 있다는 게 특징이다.

모델은 두 가지 버전으로 나왔다:

Qwen3-ASR-0.6B: 가벼운 버전, 속도가 미친 듯이 빠름
Qwen3-ASR-1.7B: 성능 위주 버전, 오픈소스 중 최고 수준

여기에 더해 Qwen3-ForcedAligner-0.6B라는 보조 모델도 있는데, 이건 음성과 텍스트를 정밀하게 정렬해서 단어 단위로 타임스탬프를 붙여주는 역할을 한다.

Feature

1. All-in-one

이 모델이 지원하는 언어를 보고 좀 놀랐다

우선 한국어 ASR 모델이 많이 없는데, 한국어가 된다는 것에 매우 감사했고, 엄청나게 다양한 언어들을 지원할 뿐만 아니라 자동언어 식별 기능이 내장되어 있어서, 어떤 언어인지 미리 알려주지 않아도 알아서 판단한다.

2. Excellent and Fast

벤치마크 결과를 보면 확실히 알 수 있다:

데이터셋	Whisper-large-v3	Qwen3-ASR-0.6B	Qwen3-ASR-1.7B
Librispeech (clean)	1.51	2.11	1.63
GigaSpeech	9.76	8.88	8.45
WenetSpeech (net)	9.86	5.97	4.97
언어 식별 정확도 (평균)	94.1%	96.8%	97.9%

특히 WenetSpeech에서 Whisper의 절반 수준인 4.97을 기록한 건 꽤 인상적이었다. OpenAI의 Whisper-large-v3가 음성 인식의 강자로 여겨졌는데, 드디어 제대로 된 경쟁자가 나온 셈이다.(자세한 벤치마크는 HF에 나와있다)

3. 스트리밍과 배치 처리 둘 다 된다

보통 ASR 모델은 스트리밍용이랑 오프라인용을 따로 만드는 경우가 많은데, Qwen3-ASR은 단일 모델로 두 가지를 다 지원한다. 실시간 음성 인식이 필요할 때도, 이미 녹음된 파일을 처리할 때도 같은 모델을 쓸 수 있다는 것이다.

게다가 5분 이상의 긴 오디오도 문제없이 처리한다고 한다. 팟캐스트나 강의 같은 긴 콘텐츠에도 바로 적용 가능하겠다.

4. Novel and strong forced alignment Solution

Qwen3-ForcedAligner-0.6B를 함께 쓰면 단어/문자 수준의 타임스탬프를 얻을 수 있다. 이게 왜 중요하냐면, 자막 생성이나 음성 분석 같은 작업에 필수적이기 때문이다. 강제 정렬(Forced Alignment) 성능도 기존 모델들을 압도한다:

이건 글 하단에서 다루도록 하겠다.

중국어: 33.1ms (기존 NFA는 109.8ms)
영어: 37.5ms (기존 WhisperX는 92.1ms)
평균: 42.9ms (기존은 129.8~161.1ms)

평균 오차가 42.9ms라는 건, 거의 눈 깜빡할 새도 없는 수준의 정확도다.

How to use

설치부터 실행까지 생각보다 간단했다.

1. 설치

conda create -n qwen3-asr python=3.12 -y
conda activate qwen3-asr
# 기본 설치
pip install -U qwen-asr

# vLLM 백엔드 포함 (더 빠름, 권장)
pip install -U qwen-asr[vllm]

나는 vLLM 버전으로 설치했는데, 속도가 확실히 체감될 정도로 빨랐다.

2. 기본 사용법 (Transformers 백엔드)

import torch
from qwen_asr import Qwen3ASRModel

# 모델 로드
model = Qwen3ASRModel.from_pretrained(
    "Qwen/Qwen3-ASR-1.7B",
    dtype=torch.bfloat16,
    device_map="cuda:0",
    max_inference_batch_size=32,
    max_new_tokens=256,
)

# 음성 인식 실행
results = model.transcribe(
    audio="https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-ASR-Repo/asr_en.wav",
    language=None,  # 자동 언어 식별
)

print(results[0].language)  # 언어 출력
print(results[0].text)      # 인식된 텍스트

language=None으로 설정하면 자동으로 언어를 감지해 준다. 이게 진짜 편한 게, 여러 언어가 섞인 데이터를 처리할 때 일일이 지정 안 해줘도 된다는 것이다.

2-1. vLLM으로 더 빠르게

import torch
from qwen_asr import Qwen3ASRModel

if __name__ == '__main__':
    model = Qwen3ASRModel.LLM(
        model="Qwen/Qwen3-ASR-1.7B",
        gpu_memory_utilization=0.7,
        max_inference_batch_size=128,
        max_new_tokens=4096,
    )

    results = model.transcribe(
        audio=[
            "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-ASR-Repo/asr_zh.wav",
            "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-ASR-Repo/asr_en.wav",
        ],
        language=["Chinese", "English"],
    )

    for r in results:
        print(r.language, r.text)

vLLM 백엔드는 배치 처리에 최적화되어 있어서, 여러 파일을 한꺼번에 처리할 때 훨씬 효율적이다. 공식 문서에 따르면 0.6B 모델의 경우 동시성 128일 때 2000배 처리량을 보여준다고 한다.

2-2. 타임스탬프 포함 인식

results = model.transcribe(
    audio=["audio1.wav", "audio2.wav"],
    language=["Chinese", "English"],
    return_time_stamps=True,
    forced_aligner="Qwen/Qwen3-ForcedAligner-0.6B",
)

for r in results:
    print(r.language, r.text, r.time_stamps[0])

return_time_stamps=True만 추가하면 각 단어가 언제 시작하고 끝나는지 정확한 시간 정보를 얻을 수 있다.

3. OpenAI API compatible server

vLLM으로 서버를 띄우면 OpenAI API 형식으로 호출할 수 있다. 이미 OpenAI SDK를 쓰고 있다면 엔드포인트만 바꾸면 된다는 것이다.

3-1 vllm 서빙

vllm serve Qwen/Qwen3-ASR-1.7B

3-2.Python request

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="EMPTY"
)

response = client.chat.completions.create(
    model="Qwen/Qwen3-ASR-1.7B",
    messages=[{
        "role": "user",
        "content": [{
            "type": "audio_url",
            "audio_url": {"url": "https://...asr_en.wav"}
        }]
    }],
)

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

3-3. cuRL request

curl http://localhost:8000/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "messages": [{
            "role": "user",
            "content": [{
                "type": "audio_url",
                "audio_url": {"url": "https://...asr_en.wav"}
            }]
        }]
    }'

이렇게 하면 기존 시스템에 통합하기가 훨씬 쉬워진다. OpenAI의 Whisper API를 쓰고 있었다면 거의 그대로 교체 가능한 수준이다

Qwen3-ForcedAligner

Forced Alignment는 음성과 텍스트를 정밀하게 맞추는 기술이다. 쉽게 말해, "이 단어는 정확히 몇 초부터 몇 초까지 말했다"는 정보를 자동으로 찾아내는 것이다.

이 기능은 자막 제작, 음성 분석, 언어 학습 앱 등에서 필수적이다. 예를 들어:

자막 싱크: 영상과 자막의 타이밍을 정확하게 맞춤
음성 분석: 특정 단어가 언제 나왔는지 추적
언어 학습: 발음 교정 시 단어별 발음 시간 측정

전통적인 도구로는 Montreal Forced Aligner(MFA)가 유명한데, 설정이 복잡하고 언어별로 따로 모델을 관리해야 했다.

WhisperX 같은 최신 ASR 기반 방법도 나왔지만, 정확도가 기대만큼은 아니었다.

Qwen3-ForcedAligner는 NAR(Non-Autoregressive) 방식을 쓴다. 기존의 순차적 방식과 달리 한 번에 모든 타임스탬프를 예측해서 속도가 빠르고, 11개 언어를 단일 모델로 처리한다.(이것도 11개 언어 중에 한국어가 포함되어 있어서 너무 기쁘다)

성능 비교를 보면 차이가 명확하다:

언어	WhisperX	NFA	Qwen3-ForcedAligner
중국어	-	109.8ms	33.1ms
영어	92.1ms	-	37.5ms
평균	161.1ms	129.8ms	42.9ms

3배 이상 정확하다는 것이다. 실제로 써보면 자막이 거의 완벽하게 동기화되는 걸 볼 수 있다.

ASR 없이 Forced Aligner만 쓸 수도 있다:

import torch
from qwen_asr import Qwen3ForcedAligner

model = Qwen3ForcedAligner.from_pretrained(
    "Qwen/Qwen3-ForcedAligner-0.6B",
    dtype=torch.bfloat16,
    device_map="cuda:0",
)

results = model.align(
    audio="audio.wav",
    text="甚至出现交易几乎停滞的情况。",
    language="Chinese",
)

# 각 단어의 시작-종료 시간 출력
for word in results[0]:
    print(word.text, word.start_time, word.end_time)

이미 텍스트를 알고 있을 때(예: 대본이 있는 영상) 정확한 타이밍만 필요하면 이렇게 쓸 수 있다.

Docker를 선호한다면 공식 이미지를 쓸 수 있다:

LOCAL_WORKDIR=/path/to/workspace
docker run --gpus all --name qwen3-asr \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -p 8000:80 \
    --mount type=bind,source=$LOCAL_WORKDIR,target=/data/shared/Qwen3-ASR \
    --shm-size=4gb \
    -it qwenllm/qwen3-asr:latest

--gpus all은 GPU를 쓰기 위한 옵션이고, --shm-size=4gb는 공유 메모리를 충분히 확보하기 위한 것이다. 배치 처리를 할 때 메모리가 부족하면 에러가 날 수 있어서 이 부분은 꼭 설정해 주는 게 좋다.

마무리

요즘 HuggingFace를 하루에 몇백 번씩 들락날락거리면서 추세를 보아하니 한 두세 달 전까지는 VLM기반의 OCR 모델들이 열풍이었고(아직도 계속해서 출시되고 있는데 이제 경량화에 들어간 모습),
얼마 전부터는 ASR, TTS 등의 task를 가진 모델들이 치열하게 경쟁 중인 것 같다.

Qwen3-ASR-1.7B는 오픈소스 음성 인식 분야에서 꽤 의미 있는 발전이라고 생각한다. Whisper가 나왔을 때도 놀라웠는데, 이번에는 더 빠르고 정확한 모델이 Apache 2.0 라이선스로 나왔다는 게 반갑다.

즉 핵심은 이 3가지다!!

다국어 지원: 30개 언어 + 22개 방언을 단일 모델로 처리
상용급 성능: Whisper와 경쟁 가능한 수준의 정확도
타임스탬프: Forced Aligner로 단어 단위 정밀 정렬

나중에 시간 나면 실제 프로젝트에 적용해 보고 후속 편을 써볼 예정이다. 궁금한 점이나 더 자세한 내용은 공식 Github이나 HuggingFace 모델 카드를 참고하길 바란다!

추가로 방금 전 Technical Report도 공개되었으니 더욱 자세 한 정보는 확인해 보길 바란다.

Paper page - Qwen3-ASR Technical Report

Join the discussion on this paper page

huggingface.co

참고 자료

STAX - 구글이 내놓은 LLM 평가 플랫폼

창빵맨 — Mon, 26 Jan 2026 15:36:46 +0900

오늘은 최근 구글에서 공개한 STAX라는 LLM 평가 플랫폼에 대해 알아보려 한다.

LLM을 프로덕션에 적용하려는 개발자라면 모델 평가가 얼마나 골치 아픈 문제인지 알 것이다.
나도 처음에는 "그냥 써보고 괜찮으면 되는 거 아냐?"라고 생각했는데, 막상 실제 서비스에 적용하려니 "이게 정말 잘 작동하는 건가?"라는 의문도 들고 하루에도 몇십 개씩 모델이 나오기 때문에 평가가 필수적이었다.

구글은 이런 문제를 "Vibe Testing(감각적 판단)"이라고 부르며, STAX를 통해 이를 해결하겠다고 나섰다. 과연 어떤 플랫폼인지 한번 파헤쳐보자!

STAX가 뭐길래?

STAX는 구글이 만든 LLM 평가 전문 플랫폼이다. 공식 슬로건이 꽤 인상적인데, "Stop chasing generic benchmarks. Start building for your users"라고 한다. 번역하자면 "일반적인 벤치마크 쫓아다니지 말고, 너네 유저를 위한 평가를 해라"는 뜻이다.

쉽게 말해, MMLU나 HumanEval 같은 일반 벤치마크는 모델의 전반적인 성능은 알려주지만, 내 서비스에 필요한 특정 능력(예: 의료 안전성, 법률 준수 등)은 측정하기 어렵다는 것이다. STAX는 바로 이 지점을 공략한다.

핵심 특징

STAX의 핵심은 딱 3가지다!!

빠른 평가, 빠른 배포: 수동 테스트를 자동화된 평가로 대체해서 개발 속도를 높인다
의미 있는 측정: 일반 벤치마크가 아니라 내 제품, 내 유저에 맞춘 맞춤형 메트릭으로 평가
데이터 기반 의사결정: 감으로 하는 게 아니라 정확한 수치와 성능 지표로 출시 준비 상태를 파악

기존 LLM 평가의 문제점

기존에 LLM을 평가하려면 어떻게 했을까? 크게 3가지 방법이 있었다.

1. "Vibe Testing" (감각적 판단)

말 그대로 "이거 좋은 것 같은데?" 하는 느낌으로 판단하는 것이다. 나도 처음에는 이렇게 했는데, 문제는 재현성이 없다는 거다. 오늘은 좋아 보이는데 내일 보면 별로고, 사람마다 판단이 다르다.

2. Generic Benchmarks (일반 벤치마크)

MMLU, HumanEval 같은 리더보드 벤치마크는 분명 유용하다. 하지만 이건 모델의 전반적인 능력을 측정할 뿐이다. 내가 만드는 의료 챗봇이 정말 안전한지, 법률 상담 봇이 규정을 준수하는지는 알 수 없다.

3. Human Raters (사람 평가자)

사람이 직접 평가하는 게 가장 정확하긴 한데, 문제는 느리고, 비싸고, 일관성 유지가 어렵다는 것이다. 평가자마다 기준이 다를 수 있고, 대량 평가는 사실상 불가능하다.

LLM은 왜 기존 테스트가 안 통할까?

일반적인 소프트웨어는 단위 테스트(Unit Test)가 잘 먹힌다. 같은 입력에 같은 출력이 나오니까. 그런데 LLM은 비결정적(Non-deterministic)이다. 같은 질문을 해도 매번 다른 답이 나올 수 있다. 그래서 기존 테스트 방식이 먹히질 않는다.

STAX가 제공하는 솔루션

STAX는 이런 문제들을 어떻게 해결할까? 크게 3단계 플라이휠(Flywheel)로 작동한다.

1. Experiment (실험)

모델, 프롬프트, AI 오케스트레이션을 빠르게 비교한다. 여러 모델을 한 번에 테스트해 보고 어떤 게 더 나은지 비교할 수 있다.

STAX는 현재 다양한 모델 프로바이더를 지원한다:

OpenAI (GPT 시리즈)
Anthropic (Claude)
Mistral
Grok
DeepSeek
Google (Gemini)
Custom 엔드포인트도 가능!

2. Evaluate (평가)

여기가 핵심이다!! STAX는 3가지 타입의 평가자(Evaluator)를 제공한다.

(1) Heuristic/Code-based (규칙 기반)

간단한 룰 기반 체크다. 예를 들어:

응답 길이가 100자 이하인가?
특정 키워드가 포함되어 있는가?
JSON 형식이 올바른가?

객관적이고 명확한 기준이 있을 때 유용하지만, 창의성이나 톤 같은 주관적 요소는 측정하기 어렵다.

(2) LLM-as-a-Judge (자동 평가)

이게 진짜 혁신적인 부분이다! 강력한 LLM(예: Gemini)이 다른 모델의 출력을 "채점"하는 방식이다.

예를 들어:

"이 답변이 친절한가?"
"사실에 부합하는가?"
"적절한 톤으로 작성되었는가?"

STAX는 미리 만들어진 평가자를 제공하면서도, 커스텀 평가 기준을 만들 수 있게 해 준다. 구글에 따르면 요즘 LLM 자동 평가자는 사람 수준에 근접했다고 한다. 빠르고, 확장 가능하고, 비용도 저렴하다!

(3) Human Raters (사람 평가)

자동 평가가 아무리 좋아도, 사람의 검증은 여전히 중요하다. STAX는 사람 평가자를 플랫폼에 통합해서 calibration(보정)과 validation(검증)에 활용할 수 있게 했다.

3. Analyze (분석)

평가 결과를 시각적으로 추적하고 집계해 준다. "시간에 따른 성능 변화"를 볼 수 있어서, 모델이나 프롬프트를 업데이트했을 때 실제로 개선되었는지 명확히 알 수 있다.

데이터셋 관리

STAX는 평가를 위한 데이터셋 관리 기능도 제공한다. 크게 3가지 방법으로 데이터셋을 만들 수 있다:

기존 데이터 업로드: 이미 가지고 있는 프로덕션 데이터를 가져올 수 있음
직접 생성: 플랫폼 내에서 새로 만들기
LLM으로 합성 데이터 생성: 모델을 활용해서 synthetic dataset을 자동 생성!

사람 평가와 자동 평가를 조합해서 벤치마크를 구축할 수 있다는 점도 매력적이다.

데이터 프라이버시는?

많은 사람들이 궁금해할 부분인데, 구글은 명확히 밝혔다:

"Google will neither own user data (including prompts, custom datasets, or evaluators) nor use it to train its language models."

즉, 내가 STAX에 올린 데이터를 구글이 가져가지도 않고, 모델 학습에 쓰지도 않는다는 것이다. 안심하고 써도 될 것 같다.

가격은?

현재 베타 기간 동안은 무료다! 다만 구글은 베타 이후 가격 정책을 도입할 수 있다고 밝혔다. 지금이 써볼 기회인 셈이다.

접근 방법은 간단하다. stax.withgoogle.com에 구글 계정으로 로그인하면 된다. Discord 커뮤니티 지원과 상세 문서도 제공한다고 한다.

요약

STAX의 진짜 가치를 이해하려면 기존 방식과 비교해봐야 한다.

기존 방식의 한계

방식	장점	단점
Vibe Testing	빠르고 간단	주관적, 재현 불가, 데이터 없음
Generic Benchmarks	객관적, 비교 용이	도메인 특화 요구사항 측정 불가
Human Raters	가장 정확	느림, 비쌈, 일관성 유지 어려움

STAX의 차별점

맞춤형 평가: Fluency, Factuality, Safety 등 내 서비스에 필요한 기준으로 평가
자동화 + 사람: LLM-as-a-Judge로 확장 가능하면서도 사람 검증 가능
멀티 메트릭, 멀티 데이터셋: 한 번에 여러 측면을 평가해서 종합적인 성능 파악
반복 가능한 파이프라인: "감"이 아니라 구조화된, 엔지니어링 된 평가

쉽게 말해, ad-hoc(임시방편)에서 시스템적인 평가로 전환하는 거다.

실제로 써볼 만한가?

솔직히 말해서, 아직 베타 단계라 실제 프로덕션에서 얼마나 효율적인지는 더 지켜봐야 할 것 같다. 다만 구글 DeepMind와 Google Labs의 평가 전문성을 녹여냈다는 점에서 기대는 된다.

특히 다음과 같은 상황이라면 써볼 만하다:

도메인 특화 LLM 서비스를 만들고 있다면 (의료, 법률, 금융 등)
여러 모델/프롬프트를 비교해야 하는 상황
평가 기준을 명확히 정의하고 싶다면
시간에 따른 성능 변화를 추적하고 싶다면

반대로, 단순히 "한 번 써보고 괜찮으면 되는" 정도의 간단한 프로젝트라면 오버킬일 수도 있다.

마무리하며

STAX는 LLM 평가의 패러다임을 바꾸려는 구글의 야심작이다. "Vibe Testing"에서 벗어나 데이터 기반의 체계적인 평가를 가능하게 해 준다는 점에서 의미가 크다.

현재 베타라서 무료로 써볼 수 있으니, LLM 프로젝트를 진행 중이라면 한번 테스트해 보는 걸 추천한다. 나도 조만간 실제 프로젝트에 적용해 보고, 경험을 공유해 볼 생각이다.

다음에는 STAX를 실제로 써본 후기와 구체적인 사용법에 대해서 작성해 볼 예정이다!

Let's be Developers

ClaudeCode 로컬 모델 사용법

Qwen3 Coder Next

vLLM 서빙

Requirements

Installation

vLLM 서버 시작

Claude Code 연결

환경변수 설정

모델 지정해서 실행

연결 확인

실제 사용 경험

References

Ubuntu 워크스페이스에서 앱이 다른 화면으로 이동하는 문제

문제

원인

해결 방법

1. --new-window 플래그 (가장 범용적)

2. --no-single-instance 플래그

3. 앱 자체 실행 경로 확인

앱 아이콘(런처)에 영구 적용하기

안 되는 경우

주요 앱별 정리

BOJ Mate 개발기

Intro

Features

문제 관리가 자동화된다

⚡ 테스트 실행이 한 번에

코드 제출도 VS Code 안에서

AI 힌트 - 막힐 때 도움받기

⏱️ 통계와 타이머

어떤 언어를 지원하나?

Installation

방법 1: VS Code Marketplace에서 설치

방법 2: VSIX 파일로 설치

사용법은?

프로젝트 배경

주의사항

오픈소스로

마무리

Cloudflare R2 가입 & 설정 가이드

Step 1: Cloudflare 계정 가입

Step 2: R2 버킷 생성

Step 3: 퍼블릭 액세스 설정

Step 4: API 토큰 생성

Step 5: .env에 추가

Step 6: Python으로 업로드 테스트

Claudian-옵시디언에서 Claude Code 사용하기

Claudian

Features

Installation

1. Release에서 직접 다운로드(추천)

2. BRAT 사용

3. 소스에서 빌드

Settings

Requirements

Summary

Daggr - HuggingFace의 새로운 AI 워크플로우 도구

Daggr가 뭐냐면

Background

기존 방식의 문제점

Daggr의 해결책

핵심 기능들

1. 코드 기반 + 자동 시각화

2. 노드별 재실행

3. Gradio 통합

4. 상태 지속성 (State Persistence)

지원하는 노드 타입

1️⃣ GradioNode - Gradio Space 또는 로컬 앱

2️⃣ FnNode - 커스텀 Python 함수

3️⃣ InferenceNode - HuggingFace Inference Providers

설치 및 실행

설치

배포

현재 상태 및 주의사항

마무리

Microsoft VibeVoice-ASR

VibeVoice-ASR

Features

1. 60-minute Single-Pass Processing

1. `--new-window` 플래그 (가장 범용적)

2. `--no-single-instance` 플래그

Step 5: `.env`에 추가