변호사 AX 나노디그리AX 나노디그리
설치가이드 · 모델 연결 · 실습용 키

LiteLLM 연결가이드 (Windows 10/11)

설치 4 / 7💻 Windows 10 / 11

대상: Windows 10/11 노트북 · 작성일 기준 2026-08-06

📌 설치할 것이 없습니다. LiteLLM은 주관사(길드)가 운영하는 AI 모델 창구로, 여러 AI 모델을 하나의 주소로 묶어 둔 것입니다. 수강생이 하는 일은 주소와 키를 도구에 등록하는 것 하나이며 도구당 약 5분 걸립니다.

🔐 보안 수칙

  • 실습용 키를 문서·메모장·카카오톡·메일에 적지 마세요. 받은 화면에서 바로 붙여넣습니다.
  • 키가 보이는 화면을 캡처해 보내지 마세요. 질문할 때는 오류 문구만 전달합니다.
  • 키가 노출됐다고 판단되면 즉시 Facilitator에게 폐기를 요청하세요 (6절).
  • 이 키는 실습 전용입니다. 실제 의뢰인 자료·사건번호를 입력하지 마세요.

1. 준비물

  • 연결할 도구 설치 완료 → 헤르메스 (2절) 또는 파이(Pi) (4절)
  • 실습용 키 — sk- 로 시작하는 문자열. 수령 방법·시점은 교육 당일 안내를 따르세요.
  • 서버 주소 — 아래 한 줄. 타이핑하지 말고 복사해서 쓰세요.
주소창에 붙여넣기
https://aiagentguild-litellm-265093816090.asia-northeast3.run.app/v1

2. 헤르메스에 등록하기

① PowerShell에 아래를 붙여넣고 Enter.

검색창에 입력
hermes model

예상 결과: 모델·제공자를 고르는 목록이 열립니다. 화살표 ↑ ↓ 로 이동, Enter 로 선택.

② 목록에서 Custom endpoint 로 시작하는 항목을 고릅니다. 버전에 따라 괄호 안 표기가 다릅니다 — 어느 쪽이든 같은 항목입니다.

복사해서 쓰기
Custom endpoint (enter URL manually)
Custom endpoint (self-hosted / VLLM / etc.)

예상 결과: 주소를 입력하라고 물어봅니다.

⚠️ OpenAI 를 고르면 안 됩니다. OpenAI 본사로 요청이 가서 인증에 실패합니다. 반드시 위 Custom endpoint 항목입니다. (헤르메스 가이드에는 "사용자 지정 엔드포인트" 로 적혀 있습니다 — 같은 항목입니다.)

③ API base URL — 1절의 주소를 복사해 붙여넣고 Enter.

④ API compatibility mode 를 물어보면 — 2. Chat Completions 를 고릅니다. (주관사 LiteLLM 서버는 표준 OpenAI 호환 방식입니다. 이 화면이 안 나오면 그냥 다음으로 넘어갑니다.)

⑤ API key — 실습용 키를 붙여넣고 Enter.

⑥ Model name — 모델 이름을 붙여넣고 Enter. 표준 구성은 legal-fast legal-work scout cross-check codex 다섯 가지이며, 어느 것을 쓸지는 당일 안내를 따르세요.

예상 결과: 설정이 저장됐다는 안내가 나오고 입력 대기 줄로 돌아옵니다.

🔑 모델 이름은 위 표준 구성과 당일 안내를 따르세요. 인터넷에서 본 다른 모델 이름을 넣으면 오류가 납니다.

3. 테스트 (1분)

헤르메스를 실행합니다.

검색창에 입력
hermes

입력창에 아래를 붙여넣고 Enter.

복사해서 쓰기
가상의 임대차 분쟁 사례를 하나 만들고, 임차인 입장의 쟁점 3가지를 정리해 줘. 실제 사건 정보는 사용하지 마.

예상 결과: 쟁점 3가지가 정리되어 돌아옵니다. 답이 오면 연결 성공입니다. (세션 중 모델 변경은 입력창에 /model custom:모델이름.)

4. 파이(Pi)에 등록하기

파이는 설정 파일에 제공자를 추가하는 방식입니다. 파이를 한 번 실행해 본 뒤 진행하세요 (설정 폴더가 만들어집니다).

① 설정 파일 열기 — PowerShell에 붙여넣고 Enter.

PowerShell에 붙여넣기
notepad "$env:USERPROFILE\.pi\agent\models.json"

예상 결과: 메모장이 열립니다. "파일을 만들까요?"라고 물으면 예를 누르세요.

② 아래를 붙여넣고, 여기에-실습용-키-붙여넣기 자리만 실습용 키(sk-...)로 바꾼 뒤 저장(Ctrl + S)하고 메모장을 닫습니다. 메모장이 비어 있지 않으면 통째로 덮어쓰지 마세요 — 기존 설정이 사라집니다. 이미 providers 가 있다면 그 중괄호 안에 "guild": { ... } 부분만 이어 붙이세요.

설정 파일에 붙여넣기
{
  "providers": {
    "guild": {
      "baseUrl": "https://aiagentguild-litellm-265093816090.asia-northeast3.run.app/v1",
      "api": "openai-completions",
      "apiKey": "여기에-실습용-키-붙여넣기",
      "models": [
        { "id": "legal-fast", "name": "Legal Fast" },
        { "id": "legal-work", "name": "Legal Work" },
        { "id": "scout", "name": "Scout" },
        { "id": "cross-check", "name": "Cross Check" },
        { "id": "codex", "name": "Codex" }
      ]
    }
  }
}

🔐 이 파일에는 키가 그대로 저장됩니다. 파일을 화면 공유·캡처에 노출하지 말고, 노트북을 반납·양도할 때는 이 파일의 키를 지우세요 (6절).

③ 확인 — 파이를 실행하고 입력창에 아래를 입력합니다.

AI 프로그램에 입력
/model

예상 결과: 모델 목록에 legal-fast legal-work scout cross-check codex 가 보입니다. 골라서 쓰면 연결 성공입니다.

🔑 위 5개가 이 교육의 표준 모델 구성입니다. 목록이 다르게 안내되면 당일 안내가 우선입니다. 파일을 고친 뒤 /model 을 다시 열면 반영됩니다(재시작 불필요).

다른 도구는? Codex CLI 는 ChatGPT 계정 로그인만 쓰므로 LiteLLM 연결 대상이 아닙니다. 안티그래비티는 구글 계정 로그인 방식이니 당일 안내를 따르세요.

5. 문제 해결

① 인증 실패 · Authentication Error

키가 잘못 전달됐습니다. 헤르메스는 2절을 다시 실행하고 키를 처음부터 다시 복사해 붙여넣으세요. 파이는 4절 ②의 models.json 을 다시 열어 apiKey 값이 sk- 로 시작하는 실제 키로 바뀌어 있는지(placeholder 그대로 아닌지) 확인하세요. 그래도 안 되면 Facilitator에게 오류 문구만 전달하세요 (키 값은 보내지 마세요).

② 모델을 찾을 수 없다는 오류

넣은 모델 이름이 이 서버에 없는 값입니다. 당일 안내받은 이름을 대소문자·하이픈까지 그대로 다시 넣으세요.

③ 연결이 안 된다 · 응답 없이 계속 대기

크롬 주소창에 아래를 붙여넣어 서버 상태를 확인합니다.

주소창에 붙여넣기
https://aiagentguild-litellm-265093816090.asia-northeast3.run.app/health/liveliness

"I'm alive!" 가 보이면 서버는 정상이므로 도구 설정 문제입니다. 화면이 안 열리면 사내 방화벽 차단이니 휴대폰 테더링으로 재시도하고, 그래도 안 되면 보안 프로그램을 임의로 끄지 말고 담당자와 Facilitator에게 알리세요.

④ 원인을 모르겠을 때 — 확인 명령 (안 될 때만)

도구를 빼고 서버에 직접 물어봅니다. PowerShell에 두 블록을 차례로 붙여넣으세요.

PowerShell에 붙여넣기
$key = Read-Host "실습용 키를 붙여넣고 Enter"
PowerShell에 붙여넣기
try { (Invoke-RestMethod -Uri "https://aiagentguild-litellm-265093816090.asia-northeast3.run.app/v1/models" -Headers @{ Authorization = "Bearer $key" }).data.id } catch { $_.ErrorDetails.Message }

예상 결과: 쓸 수 있는 모델 이름 목록이 나옵니다. 나오면 주소·키는 정상이고 원인은 도구 설정입니다. No api key passed in 은 키가 담기지 않은 것(첫 블록부터 다시), Invalid proxy server token 은 키가 틀렸거나 폐기된 것(①로)입니다.

6. 키가 노출됐다면

실습용 키의 폐기·재발급은 주관사만 할 수 있습니다. 노출이 의심되면 즉시 Facilitator에게 알리세요 — 늦게 알리는 것이 노출 자체보다 큰 문제입니다. 이때도 키 값은 보내지 말고 상황만 전달하면 관리자가 찾아 폐기합니다. 교육이 끝난 뒤 키 정리 시점은 당일 안내를 따르세요. 파이를 썼다면 교육이 끝나면 models.json 을 다시 열어(4절 ①) apiKey 값을 지우거나 파일을 삭제하세요 — 도구에서 연결만 끊어도 파일 속 키는 남아 있습니다.

막히면: 오류 화면을 캡처(Windows 키 + Shift + S)해 Facilitator 에게 보내세요. 키가 보이면 반드시 가리고 보냅니다.

확인 출처 (2026-08-06): 서버 주소·/health/liveliness 응답·인증 오류 문구는 해당 서버에 직접 요청해 확인. 연결 방식은 LiteLLM 공식 문서, 헤르메스 Custom endpoint 절차는 헤르메스 공식 문서, 파이 ~/.pi/agent/models.json(Windows: %USERPROFILE%\.pi\agent\models.json)·apiKey 필드·/model 즉시 반영은 파이 공식 문서 기준. 실습용 키 발급 절차·모델 목록·사용 한도는 확인 불가 — 당일 안내를 따르세요.