본문 바로가기
문서 목차
KosmosAI v1.0.2따라 하기

외부 모델 가져와 서빙하기

HuggingFace 의 언어 모델(LLM)을 모델 레지스트리로 가져와 추론(서빙)하고, AI Gateway 를 통해 채팅·에이전트·외부 프로그램에서 부르는 과정을 따라 합니다.

QUANTUM C&S

HuggingFace 의 언어 모델(LLM)을 모델 레지스트리로 가져와 추론(서빙)하고, AI Gateway 를 통해 채팅 · 에이전트 · 외부 프로그램에서 부르는 과정을 따라 합니다.

이런 일을 할 수 있어요

  • HuggingFace 모델을 검색해 레지스트리에 등록하고, 모델 파일을 백그라운드 다운로드 작업으로 받아 둡니다.
  • 받은 모델을 OCI 이미지(모델카) 로 만들어 두면, 배포할 때 모델 다운로드 단계 없이 빠르게 뜹니다.
  • 배포 마법사로 LLM 을 서빙하고, 테스트 탭에서 바로 대화해 봅니다.
  • AI Gateway 에 노출하면 플랫폼의 채팅 · 에이전트와 외부 프로그램이 정해진 이름으로 그 모델을 부릅니다.

전체 흐름

단계 화면 결과물
1. 가져오기 모델 › 레지스트리 › 외부 모델 가져오기 레지스트리에 모델 등록
2. 파일 받기 모델 상세 › S3로 다운로드, 다운로드 메뉴 플랫폼 저장소에 모델 파일
3. (선택) 모델카 모델 상세 › OCI 이미지로 푸시 모델이 든 컨테이너 이미지
4. 서빙 추론 › 배포 마법사 LLM 추론 서비스
5. 노출 · 호출 추론 목록 · 상세 › AI Gateway 에 노출 게이트웨이 모델 이름

시작하기 전에

  • 접근 제한(gated) 모델이나 비공개 모델은 플랫폼 관리자가 플랫폼 설정 › 모델 레지스트리에 HuggingFace 토큰을 등록해 두어야 받을 수 있습니다. 토큰 계정으로 HuggingFace 웹사이트에서 라이선스 동의도 필요합니다.
  • LLM 서빙에는 대개 GPU 가 필요합니다. 내 팀(프로젝트)의 GPU · CPU · 메모리 할당량을 리소스 현황이나 프로젝트의 사용량 · 쿼터에서 확인해 두세요.

따라 하기

1단계: HuggingFace 모델 가져오기

  1. 왼쪽 메뉴 모델 › 레지스트리로 이동해 오른쪽 위 외부 모델 가져오기를 누릅니다.
  2. HuggingFace 탭의 검색 칸에 모델 이름(예: qwen, llama)을 입력하고 검색을 누릅니다.
  3. 결과에서 모델을 고릅니다. 이미 가져온 모델에는 가져옴 표시가 있습니다.
  4. 옵션을 정합니다.
    • 모델 이름: 비우면 HuggingFace ID 를 그대로 씁니다.
    • 공개 범위: 프로젝트 공개, 비공개(나만), 전체 공개 중 하나.
    • 파일 다운로드: 체크하면 등록과 함께 모델 파일 다운로드를 시작합니다.
  5. 모델 가져오기를 누릅니다. 완료되면 "가져오기 완료" 와 함께 "'<모델 이름>' 을(를) 모델 레지스트리에 등록했습니다." 가 표시되고, 모델 열기로 상세 화면으로 갈 수 있습니다.

외부 모델 가져오기 창 — HuggingFace·MLflow Sync 탭

팁 같은 모델이 이미 등록되어 있으면 "중복 모델 발견" 안내가 나옵니다. 계속하면 기존 모델에 새 버전이 추가되거나 덮어씌워질 수 있으니 확인 후 진행하세요.

2단계: 모델 파일 내려받기

가져오기에서 파일 다운로드를 체크하지 않았다면 다음과 같이 받습니다.

  1. 모델 상세 화면에서 S3로 다운로드를 누릅니다.
  2. "다운로드 작업이 시작되었습니다. 브라우저를 닫아도 백그라운드에서 계속 진행됩니다." 안내가 나옵니다.
  3. 진행 상황은 상세 화면(파일 진행 수)과 왼쪽 아래 다운로드 메뉴에서 확인합니다. 끝나면 모델 확인 / 모델 보기로 돌아갈 수 있습니다.
  4. 완료된 모델에는 목록에서 S3 저장됨 배지가 붙고, 상세 화면에 배포 버튼이 나타납니다.

주의 다운로드가 실패하면 상세 화면에 원인이 표시됩니다. 접근 제한 모델이면 "이 모델은 접근 제한(gated) 모델입니다." 와 함께 토큰 등록 · 라이선스 동의 방법이 안내됩니다. 자주 묻는 질문의 "모델 다운로드가 실패해요"를 참고하세요.

3단계: (선택) OCI 이미지(모델카)로 만들기

모델카(modelcar)는 모델 파일을 컨테이너 이미지 안에 미리 담아 두는 방식입니다. 서빙 파드가 뜰 때 저장소에서 모델을 내려받지 않아 기동이 빨라집니다.

  1. 모델 파일 다운로드가 끝난 모델 상세에서 OCI 이미지로 푸시를 누릅니다(모델을 고칠 권한이 있을 때 보입니다).
  2. "OCI 이미지 빌드를 시작했습니다. 모델 크기에 따라 수 분 걸립니다." 안내 후 버튼이 OCI 빌드 중으로 바뀝니다.
  3. 완료되면 OCI 저장됨 배지가 붙고 버튼은 OCI 이미지 갱신으로 바뀝니다.

4단계: LLM 추론 서비스 배포

  1. 모델 상세의 배포를 누르거나 추론 화면에서 배포 마법사를 누릅니다. 새 추론 서비스 배포 화면이 모델 선택 → 런타임 선택 → 리소스 설정 → 검토 & 배포 4단계로 열립니다.
  2. 모델 선택
    • 모델 파일로 띄우려면 Model Registry에서 선택을 고르고 모델과 버전을 선택합니다.
    • 3단계에서 모델카를 만들었다면 컨테이너 이미지 모델(모델 다운로드 없이 뜹니다)을 고릅니다.
  3. 런타임 선택 — LLM 은 다음 중 하나를 고릅니다.
    • llm-d: 생성형 언어 모델 전용 런타임입니다. llm-d router 에서 Standalone(기본값, 라우터 없이 서비스로 바로 연결)을 고르면 한 서비스로 단순하게 뜹니다. Gateway Mode 는 게이트웨이를 통한 캐시 인지 라우팅을 쓰는 방식으로, 복제본을 2개 이상 둘 때 고려합니다.
    • Template: 관리자가 미리 준비한 템플릿(예: vLLM)으로 배포합니다.
  4. 리소스 설정
    • 서비스 이름: 길이 제한이 있으며 남은 글자 수가 표시됩니다.
    • 네임스페이스: 내 팀(프로젝트)의 작업 공간을 고릅니다.
    • GPU 할당 방식과 개수, CPU · 메모리를 정합니다. 이 서비스에 쓸 수 있는 남은 할당량이 함께 표시됩니다.
    • 고급 설정에서 모델 저장소 접근 방식을 확인할 수 있습니다. 모델카를 쓰면 OCI 이미지 (modelcar) 로, 저장소 자격증명이 필요 없습니다.
  5. 검토 & 배포에서 설정을 확인하고 서비스 배포를 누릅니다.
  6. 서비스가 준비될 때까지 기다립니다. 큰 모델은 수 분 이상 걸릴 수 있습니다.

새 추론 서비스 배포 — 4단계와 모델 선택 방식

주의 모델카(OCI)는 GPU 공유 그룹(MPS 방식)에서는 뜨지 않습니다. 이 경우 "OCI(modelcar) 는 MPS 공유 그룹에서 뜨지 않습니다 …" 안내가 나오며, 전용 Claim 템플릿을 골라야 합니다.

5단계: 대화로 시험하기

  1. 추론 목록에서 서비스를 눌러 상세 화면을 엽니다.
  2. 테스트 탭에서 메시지를 입력하고 보냅니다. 응답이 오면 서빙이 정상입니다.
    • Template 으로 배포한 서비스: 대화 입력칸에 메시지를 넣고 전송을 누릅니다.
    • llm-d 로 배포한 서비스: Request 칸에 메시지를 넣고 Send 를 누르면 Response 칸에 답이 표시됩니다.
  3. 외부 프로그램에서 직접 부를 때는 상세 화면의 API 예시를 참고하고, 인증 헤더에 개인 액세스 토큰을 넣습니다.

6단계: AI Gateway 에 노출하고 부르기

AI Gateway(LLM 게이트웨이)는 플랫폼의 여러 모델을 하나의 OpenAI 호환 창구로 묶어 주는 관문입니다. 노출하면 채팅 · 에이전트가 그 이름으로 모델을 부릅니다.

  1. 추론 목록의 서비스 메뉴 또는 LLM 서비스 상세에서 AI Gateway 에 노출을 누릅니다.
  2. 게이트웨이 모델 이름을 확인하거나 고칩니다(영문 · 숫자로 시작하고 영문 · 숫자 · . _ - 만, 최대 63자).
  3. 노출을 누르면 "<이름> 을(를) AI Gateway 에 노출했습니다" 가 표시되고, 서비스에 AI Gateway 모델: <이름> 이 붙습니다.
  4. 이제 에이전트 만들기의 기본 LLM, 지식대화의 모델 선택 등에서 이 모델을 고를 수 있습니다(사용 권한이 있는 경우).
  5. 외부 프로그램에서 게이트웨이를 직접 부르려면 플랫폼 관리자가 플랫폼 설정 › AI Gateway › API 키에서 발급한 키가 필요합니다.
curl https://<게이트웨이 주소>/v1/chat/completions \
  -H "Authorization: Bearer <발급받은 게이트웨이 키>" \
  -H "Content-Type: application/json" \
  -d '{"model":"<게이트웨이 모델 이름>","messages":[{"role":"user","content":"안녕하세요"}]}'

주의 노출을 해제(노출 해제)하면 그 이름도 사라지고, 이 모델을 쓰던 대화는 더 이상 응답하지 않습니다.

참고 플랫폼 안에서 직접 띄운 모델은 내부 모델입니다. 외부 업체의 유료 LLM(외부 모델)은 별도의 외부 모델 사용 정책과 권한이 있어야 쓸 수 있습니다. 거부되면 사유와 필요한 조치가 표시됩니다 — 자주 묻는 질문 참고.

SAMANDA 에게 맡기기

SAMANDA 대화창에서 다음과 같이 요청할 수 있습니다.

  • "허깅페이스에서 Qwen/Qwen2.5-7B-Instruct 모델 등록하고 다운로드해줘"
  • "방금 등록한 모델로 추론 서비스 배포해줘"
  • "서빙 중인 모델 뭐 있어?"

SAMANDA 는 필요한 값(네임스페이스 · 서비스 이름 · GPU 등)을 물어본 뒤 계획을 먼저 보여 주고, 입력창 위 승인 필요 카드에서 승인하면 실행합니다. 모든 작업은 요청한 사람의 권한으로 실행됩니다.

또한 플로우 › AI플로우 화면의 기본 제공 템플릿 중 HuggingFace 모델 등록, 추론 서비스 배포를 고르면 SAMANDA 가 한 단계씩 물어보며 진행하는 대화형 가이드가 시작됩니다. 자세한 내용은 AI플로우를 참고하세요.

권한

  • 모델 가져오기 · 다운로드 · OCI 이미지 빌드는 모델을 만들고 고칠 권한이 필요합니다. OCI 이미지로 푸시 버튼은 모델을 고칠 수 있는 사람에게만 보입니다.
  • 추론 배포는 대상 네임스페이스에 배포할 권한과 남은 할당량이 있어야 합니다.
  • AI Gateway 의 API 키 발급은 플랫폼 관리자 기능입니다.

관련 항목