본문으로 건너뛰기

커스텀 엔드포인트

커스텀 엔드포인트 기능을 사용하면 로컬에 배포된 LLM 추론 서비스(예: Ollama, LM Studio)나 기업 전용 배포 API를 Elftia에 연결할 수 있습니다. 대부분의 로컬 추론 프레임워크는 OpenAI 호환 API를 제공하므로 설정이 간단합니다.

사용 시기​

  • 오픈 소스 모델(Llama, Qwen, Mistral 등)을 로컬에서 실행하여 완전한 오프라인 사용을 원할 때
  • 회사 내부 네트워크에 전용 LLM 서비스가 배포된 경우
  • 공식 OpenAI API 대신 Azure OpenAI Service를 사용할 때
  • 자체 호스팅 추론 클러스터(vLLM, TGI 등)에 연결해야 할 때
  • LM Studio의 그래픽 로컬 추론 환경을 사용하고 싶을 때

Ollama​

Ollama는 가장 인기 있는 로컬 모델 실행 도구로, 다양한 오픈 소스 모델을 원클릭으로 다운로드하고 실행할 수 있습니다.

사전 요구 사항​

  • Ollama 설치 (다운로드)
  • 모델 최소 1개 다운로드 (예: ollama pull llama3.1)

설정 단계​

  1. Ollama가 실행 중인지 확인합니다
    • Windows/macOS: 설치 후 기본적으로 백그라운드 서비스로 실행됨
    • Linux: ollama serve를 실행하여 서비스 시작
    • 기본 수신 주소: http://localhost:11434

  1. Elftia에서 설정 → 프로바이더 관리를 엽니다

  2. 기본 Ollama 프로바이더를 찾습니다 (없을 경우 프로바이더 추가 → Ollama 프리셋 선택)

  3. 구성을 확인합니다:

필드값
API 형식openai
Base URLhttp://localhost:11434/v1
API Key(비워 두기 — Ollama는 기본적으로 인증이 필요 없음)
  1. 다운로드한 모델을 추가합니다:
    • 모델 추가를 클릭합니다
    • Ollama에서의 모델 이름을 입력합니다 (ollama list 출력 결과와 일치해야 함)
    • 예시: llama3.1, qwen2.5:14b, codellama:34b

  1. 활성화 토글을 켜고 저장합니다

  2. 채팅 UI의 모델 선택 목록에서 Ollama 모델을 확인할 수 있습니다

Ollama 주요 모델​

모델 이름파라미터 수용도다운로드 명령
llama3.18B범용 채팅ollama pull llama3.1
llama3.1:70b70B고품질 채팅ollama pull llama3.1:70b
qwen2.5:14b14B한국어/영어 채팅ollama pull qwen2.5:14b
codellama:34b34B코드 생성ollama pull codellama:34b
deepseek-coder-v216B코드 보조ollama pull deepseek-coder-v2
mistral7B경량 채팅ollama pull mistral
llava7B비전 이해ollama pull llava

원격 Ollama​

로컬 네트워크의 다른 머신에서 Ollama가 실행 중인 경우:

  1. Ollama가 실행 중인 머신에서 환경 변수 OLLAMA_HOST=0.0.0.0:11434를 설정합니다
  2. Ollama 서비스를 재시작합니다
  3. Elftia에서 Base URL을 http://<원격-IP>:11434/v1로 변경합니다

LM Studio​

LM Studio는 로컬 모델 관리 및 추론을 위한 그래픽 인터페이스를 제공하며, OpenAI 호환 API 서버가 내장되어 있습니다.

사전 요구 사항​

  • LM Studio 설치 (다운로드)
  • 모델 최소 1개 다운로드 및 로드

설정 단계​

  1. LM Studio에서 로컬 서버를 시작합니다:
    • LM Studio를 엽니다
    • Local Server 탭으로 전환합니다
    • 모델을 로드합니다
    • Start Server를 클릭합니다
    • 서버 주소를 확인합니다 (기본값: http://localhost:1234)

  1. Elftia에서 설정 → 프로바이더 관리를 엽니다

  2. 프로바이더 추가 → 커스텀 프로바이더 선택을 클릭합니다

  3. 구성을 작성합니다:

필드값
이름LM Studio
API 형식openai
Base URLhttp://localhost:1234/v1/chat/completions
API Keylm-studio (LM Studio는 키 검증을 하지 않지만, 필드가 필수인 경우 임의의 값 입력)

  1. 모델을 추가합니다:

    • LM Studio에 로드된 모델 이름을 입력합니다
    • 모델 이름은 LM Studio에 표시된 모델 식별자와 일치해야 합니다

  2. 연결을 테스트하고 활성화한 후 저장합니다

vLLM / Text Generation Inference​

vLLM과 TGI는 프로덕션 환경에서 널리 사용되는 고성능 LLM 추론 엔진입니다. 두 서비스 모두 OpenAI 호환 API를 제공합니다.

vLLM 구성​

  1. vLLM 서비스를 시작합니다 (예시):

    python -m vllm.entrypoints.openai.api_server \
      --model meta-llama/Llama-3.1-8B-Instruct \
      --port 8000

  2. Elftia에서 커스텀 프로바이더를 추가합니다:

필드값
이름vLLM Local
API 형식openai
Base URLhttp://localhost:8000/v1/chat/completions
API Key(비워 두거나 vLLM의 --api-key 값 입력)
  1. 모델 추가: vLLM 시작 시 지정한 --model 이름을 사용합니다

TGI 구성​

  1. TGI 서비스를 시작한 후 OpenAI 호환 엔드포인트를 사용합니다

  2. Elftia에서 커스텀 프로바이더를 추가합니다:

필드값
이름TGI
API 형식openai
Base URLhttp://localhost:8080/v1/chat/completions
API Key(비워 두거나 해당 값 입력)

Azure OpenAI​

Azure OpenAI Service는 OpenAI와 동일한 모델을 사용하지만 Azure 플랫폼에서 호스팅되며, 엔터프라이즈급 SLA와 데이터 컴플라이언스 보증을 제공합니다.

사전 요구 사항​

  • Azure 구독 및 Azure OpenAI Service 접근 권한
  • Azure Portal에서 생성된 Azure OpenAI 리소스
  • 최소 1개의 모델 배포 (배포 이름 필요)

설정 단계​

  1. Azure Portal에서 다음 정보를 가져옵니다:
    • 엔드포인트(Endpoint): https://<resource-name>.openai.azure.com 형식
    • API 키: "키 및 엔드포인트" 페이지에서 확인
    • 배포 이름: "모델 배포" 페이지에서 확인
    • API 버전: 2024-08-01-preview 권장

  1. Elftia에서 설정 → 프로바이더 관리를 엽니다

  2. 프로바이더 추가 → Azure OpenAI 프리셋 선택을 클릭합니다

  3. 구성을 작성합니다:

필드값예시
API 형식azure-openai--
Base URLAzure 엔드포인트https://my-resource.openai.azure.com
API KeyAzure API 키xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
API VersionAPI 버전 번호2024-08-01-preview

  1. 모델을 추가합니다:

    • 모델 ID에 Azure 배포 이름을 사용합니다 (모델 이름이 아님)
    • 예를 들어 gpt-4o를 my-gpt4o로 배포한 경우, 모델 ID에 my-gpt4o를 입력합니다

  2. 연결을 테스트하고 활성화한 후 저장합니다

Azure와 표준 OpenAI의 차이점​

기능OpenAIAzure OpenAI
Base URLhttps://api.openai.com/v1/...https://<resource>.openai.azure.com
인증Authorization: Bearer sk-...api-key: ...
모델 지정모델 이름 사용 (예: gpt-4o)배포 이름 사용
API 버전불필요필수 (URL 파라미터)
API 형식openaiazure-openai

구성 항목 참조​

커스텀 엔드포인트 시나리오에 적용되는 구성 항목:

설정유형기본값설명
이름문자열--커스텀 표시 이름
API 형식열거형openai로컬 서비스는 보통 openai, Azure는 azure-openai 사용
Base URLURL--추론 서비스의 API 주소
API Key문자열(비어 있음)로컬 서비스는 보통 불필요; Azure는 필수
API Version문자열(비어 있음)Azure OpenAI 전용 필수, 예: 2024-08-01-preview
모델 목록배열(비어 있음)서비스에서 사용 가능한 모델 이름을 수동으로 입력
Transformer배열(비어 있음)커스텀 엔드포인트는 보통 추가 Transformer가 필요 없음

동작 참고 사항​

로컬 서비스 특별 고려 사항​

  • API 키 검증 없음: 대부분의 로컬 서비스(Ollama, LM Studio)는 API 키가 필요하지 않습니다. Elftia의 API 키 필드가 필수인 경우 임의의 값을 입력하세요
  • 모델 핫 로딩: 일부 서비스는 동적 모델 로딩을 지원합니다. 서비스에 새 모델을 추가한 후 Elftia에서 해당 모델 이름을 추가하기만 하면 됩니다
  • 동시성 제한: 로컬 서비스는 보통 한 번에 하나의 요청만 처리하므로 동시성 제한을 1로 설정하세요
  • 첫 응답 지연: 로컬 모델이 GPU 메모리에 로드되는 데 몇 초가 걸릴 수 있어 첫 번째 요청은 지연이 눈에 띌 수 있습니다

프록시 및 네트워킹​

  • 로컬 서비스(localhost / 127.0.0.1)는 글로벌 프록시를 통하지 않습니다
  • LAN 서비스는 프록시 구성에 따라 프록시 제외 목록에 추가해야 할 수 있습니다

모델 기능​

로컬 모델의 기능 플래그(비전, 함수 호출 등)는 Elftia에서 수동으로 설정해야 합니다. 모델이 비전을 지원하더라도 플래그가 설정되지 않으면 Elftia는 해당 모델에 이미지를 전송하지 않습니다.

문제 해결​

문제가능한 원인해결 방법
연결 거부됨로컬 서비스가 실행 중이지 않음Ollama/LM Studio/vLLM이 실행 중인지 확인
연결 타임아웃잘못된 포트 또는 방화벽 차단포트 번호 확인; 방화벽이 연결을 허용하는지 확인
모델을 찾을 수 없음모델 이름이 서버와 일치하지 않음ollama list 또는 서버의 모델 목록으로 이름 확인
Ollama 원격 연결 실패Ollama가 기본적으로 localhost만 수신OLLAMA_HOST=0.0.0.0:11434 설정 후 재시작
LM Studio가 빈 응답 반환모델이 메모리에 로드되지 않음LM Studio에서 모델이 로드되어 "Ready" 상태인지 확인
Azure에서 404 반환잘못된 배포 이름모델 ID로 모델 이름이 아닌 배포 이름을 사용하는지 확인
Azure에서 401 반환잘못된 API 버전 또는 키API Version 필드와 API Key 확인
응답이 깨진 문자로 표시됨모델이 해당 언어를 지원하지 않음대상 언어를 지원하는 모델로 전환 (예: Qwen, ChatGLM)
GPU 메모리 부족모델이 너무 큼더 작은 양자화 버전 선택 (예: llama3.1:8b-q4_0)
요청이 멈추고 응답 없음로컬 서비스가 모델 로딩 중모델 로딩이 완료될 때까지 기다림; 첫 번째 요청은 10~30초가 걸릴 수 있음

관련 페이지​