TabbyML 사내 파일럿 온보딩 가이드를 쓰며

TL;DR 사내 파일럿용 TabbyML(오픈소스 코드 자동완성 서버) 온보딩 가이드를 쓰며 관찰한 두 가지. 하나. 예측 가능한 함정은 트러블슈팅 섹션이 아니라 설치 단계 인라인에 못 박아야 한다. 트러블슈팅까지 가기 전에 이미 함정을 만나고, 그 순간 도구 자체에 대한 신뢰가 무너지기 때문이다. 둘. 성능이 아직 부족한 도구는 “왜 느린지”의 원인 층(CPU 추론 → GPU 전환 예정 등)까지 같이 밝혀야 피드백이 “느려서 못 씀”이 아니라 “GPU 전까진 Chat 위주로 판단” 같은 조건부 판단으로 돌아온다.

배경

사내에 TabbyML(오픈소스 코드 자동완성 서버)을 올려두고 파일럿 테스터 한두 명한테 먼저 써보게 하려고 온보딩 가이드를 쓰게 됐다. 정식 롤아웃 전 단계라 문서의 목적은 “설치 순서 안내”보다는 “이 시점에 이 도구를 처음 붙이는 사람이 헤매지 않게 하는 것”에 가까웠다.

가이드를 다 쓰고 보니 절반이 “이걸 조심해야 한다”였다. 이 글은 그 관찰에 대한 짧은 기록이다.

왜 함정 경고가 설치 순서보다 먼저 오는가

정식 릴리스가 된 상용 도구라면 설치 순서만 잘 적어두면 대부분 문제가 없다. 그런데 파일럿 단계의 오픈소스는 상황이 다르다. 실제로 이번 TabbyML 온보딩에서 명시적으로 걸린 함정이 두 개 있었다.

함정 하나. config.toml이 아닌 VS Code settings.json에 서버 주소를 넣으면 안 먹힌다.

VS Code에서 확장을 설치하면 자연스럽게 settings.json을 열어서 tabby.endpoint 같은 키를 넣게 된다. 그런데 실제로 유효한 위치는 ~/.tabby-client/agent/config.toml이다. 확장 설정과 에이전트 설정이 파일이 다르고, 확장 UI에서 이 사실을 안내해주지 않는다.

함정 둘. 서버 웹 UI가 알려주는 Endpoint URL이 잘못 나온다.

TabbyML 서버(내부망 192.168.x.x:8080)에 로그인하면 “Endpoint URL / Token” 페이지가 뜬다. 여기서 표시되는 Endpoint URL이 localhost:8080으로 나온다. 서버 자체가 자기 자신의 외부 접근 주소를 모르기 때문에 벌어지는 일인데, 사용자 입장에서는 UI가 알려주는 값을 그대로 복사해서 붙일 가능성이 높다. 그러면 당연히 접속이 안 된다.

둘 다 “설치는 다 했는데 왜 안 되지?” 단계에서 만나는 함정이다. 온보딩 문서에 미리 못 박아두지 않으면 몇 번 헤매고 나서 물어보게 된다. 그런데 그 헤매는 순간이 곧 도구 자체에 대한 신뢰가 흔들리는 지점이기도 하다.

그래서 이번 가이드에서는 설치 3단계 안에 두 함정 모두를 인라인으로 붙였다. 원문에서 뽑아보면 이런 식이다.

【설치 2단계 · 서버 정보 입력】
   - 경로: `~/.tabby-client/agent/config.toml`
   - ⚠️ VS Code `settings.json`의 `tabby.endpoint`가 아님 — 여기 넣으면 안 먹힘

【토큰 발급 페이지】
   - ⚠️ 이 페이지에 표시되는 Endpoint URL은 `localhost:8080`으로 **잘못** 나옴
     → 무시하고 위 `192.168.x.x:8080` 사용

두 경고 모두 트러블슈팅 섹션으로 빼놓지 않은 이유는 하나다. 함정을 만난 사람이 트러블슈팅 페이지를 열어보는 시점은 이미 늦기 때문이다.

성능 아직 부족한 도구는 “왜 느린지”까지 같이 말한다

지금 TabbyML 자동완성은 후보 하나당 1초 안팎, 세 개면 3초 가까이 걸린다. GitHub Copilot을 쓰던 사람 입장에서는 “얘 뭔가 고장난 거 아닌가” 싶을 속도다.

여기서 그냥 “속도가 좀 느립니다” 정도로 언급하고 넘어가면, 도구가 원래 이 정도인 줄 알게 된다. 그러면 파일럿 피드백이 “느려서 못 쓰겠다”로 수렴한다. 실제로는 추론을 GPU로 옮기면 개선될 여지가 있는 상태인데도 그렇다.

그래서 가이드 3장에 이 항목을 넣었다.

지금 자동완성이 느리게 느껴질 수 있음 (후보 하나당 ~1초, 3개면 3초 가량) → 고장 아니고, 백엔드 서버가 현재 CPU로 추론 중이라 그럼. GPU 전환 후 개선 예정.

Chat 기능은 상대적으로 빠름 (2초 이내) — 코드 설명, 질문 등에 먼저 써보길 추천

두 가지를 같이 넣었다.

지금 느린 이유는 CPU 추론이고, GPU로 옮기면 개선된다 (한계의 층을 밝힘)
상대적으로 잘 돌아가는 건 Chat이니 거기부터 써보라 (기대치 재조정)

이렇게 하면 피드백이 “속도가 안 나온다”에서 “GPU 붙기 전까진 Chat 위주로 쓰겠다” 정도로 방향이 잡힌다. 도구 자체에 대한 최종 판단은 GPU 전환 이후로 자연스럽게 미뤄진다.

문서 전체 골격

가이드 목차는 이렇게 갔다.

설치 & 연결 (3단계) — 함정 두 개를 인라인 경고로 붙임
토큰 발급 방법 — 잘못된 Endpoint URL 함정을 한 번 더 반복
미리 알아두면 좋은 것 — 성능 기대치 조정, Chat 우선 추천, 캐시 재생 현상
피드백 요청 (사용 3~5일 후) — 5개 항목 (속도·품질·Chat·설정 난이도·기타)

문서 전체 길이는 A4 한 장 안쪽. 파일럿 단계에서는 이 정도가 균형점이다 — 더 길면 안 읽고, 더 짧으면 함정에 빠진다.

참고

대상 도구: TabbyML (오픈소스 코드 자동완성 서버, 자체 호스팅)
배포 환경: 사내 서버, 추론은 별도 LLM 서버에 위임(당시 CPU 추론)
후속: 서버 구축 과정(임베딩 CUDA 크래시 · 자동완성 안 뜨는 원인 4겹)은 다음 두 편에