Xinference GitHub 추천: 로컬 LLM OpenAI 호환 API 첫 테스트와 도입 체크
v2.10.0 릴리스 기준 설치, 첫 호출, 운영 리스크를 개인 개발자 관점에서 점검
Xinference GitHub 추천: 로컬 LLM을 OpenAI 호환 API로 서빙하기
Xinference는 오픈소스 LLM, 임베딩, 음성, 멀티모달 모델을 로컬·온프레미스·클라우드에서 OpenAI 호환 REST API로 실행하는 모델 서빙 프레임워크입니다. 2026-06-06 KST 기준 v2.10.0 릴리스, 최근 push, 9,342 stars, Apache-2.0 라이선스가 확인되어 Xinference GitHub local LLM serving OpenAI compatible API 실험 대상으로 검토할 이유가 있습니다.
OpenAI SDK로 만든 작은 챗봇이나 RAG 테스트 코드가 이미 있다면 먼저 볼 지점은 분명합니다. 개인 GPU나 사내망 endpoint를 붙였을 때 기존 호출 흐름이 얼마나 남는지 확인해야 합니다. Xinference는 이 확인을 로컬 OpenAI 호환 endpoint 테스트로 줄여 줍니다.
README의 모델 목록을 훑기 전에 첫 호출 경로부터 보는 편이 낫습니다. 기존 OpenAI SDK 앱이 `http://127.0.0.1:9997/v1` 같은 로컬 endpoint로 요청을 보낼 수 있는지 확인하고, Docker 포트, metrics, 인증은 그 다음에 붙이면 됩니다.
Xinference GitHub local LLM serving OpenAI compatible API를 검토할 때는 호환 범위, 모델 라이선스, GPU 비용, 인증 설계를 분리해서 봐야 합니다. 로컬 응답 한 번은 시작 기록으로만 남기고, 운영 판단은 별도의 체크리스트에서 다루는 편이 좋습니다.
2026년 6월에 새로 확인된 신호
v2.10.0은 2026-06-05T23:00:21Z에 GitHub Releases에 올라왔고, 한국 시간으로는 2026-06-06 오전 릴리스입니다. 같은 날 GitHub API 기준 저장소 push도 확인됐습니다.
9,342 stars는 관심도를 가늠하는 보조 신호입니다. 릴리스와 push가 같은 날짜에 확인됐다는 점이 더 쓸 만한 단서입니다. 오래전에 멈춘 README를 뒤늦게 읽는 상황과는 다릅니다.
v2.10.0 릴리스에는 JSON 로그, stdout redirect, OIDC/Keycloak SSO, 감사 로그, IP/API key ban, rate limiting, 보안 감사 패널, 모델별 GPU 메모리 메트릭, launch model configuration history가 포함됐습니다. localhost 실험을 팀 PoC로 옮기면 실패 원인, 접근 기록, GPU 메모리, 요청 제한을 볼 수 있어야 합니다. 이번 릴리스 항목은 그 운영 질문과 바로 맞닿아 있습니다.
pip 설치와 localhost 호출로 작게 시작합니다
Xinference 설치는 `pip install "xinference[all]"`로 시작하고 `xinference-local`을 실행한 뒤, OpenAI SDK의 `base_url`을 `http://127.0.0.1:9997/v1`로 바꿔 Chat Completions 요청을 보내는 흐름이 가장 작습니다. 이 단계의 목표는 기존 앱 코드가 로컬 LLM endpoint까지 닿는지 확인하는 일입니다.
Docker, Kubernetes, vLLM, 여러 worker를 한 번에 올리면 실패 원인이 섞입니다. 개인 실험의 Xinference 사용법은 localhost 호출 하나로 좁히는 쪽이 선명합니다.
1. Python 환경을 만들고 `pip install "xinference[all]"`로 설치합니다.
2. `xinference-local`을 실행해 기본 endpoint `http://127.0.0.1:9997`을 띄웁니다.
3. Web UI나 CLI에서 작은 모델 하나를 launch합니다.
4. OpenAI Python SDK에서 `base_url`을 `http://127.0.0.1:9997/v1`로 지정합니다.
5. 실행 중인 model UID 또는 모델 이름으로 Chat Completions 요청을 보냅니다.
모델 상태는 `xinference list` 또는 `/v1/models`로 봅니다. 테스트를 끝낼 때는 `xinference terminate --model-uid <uid>` 같은 종료 절차도 한 번 거쳐야 GPU 메모리와 프로세스 정리 흐름을 확인할 수 있습니다.
첫날에는 성능표보다 연결 로그를 남기는 데 집중합니다. 응답이 돌아온 뒤에야 모델 품질, GPU 비용, 캐시 용량을 나눠 비교할 수 있습니다.
OpenAI 호환 API는 Chat Completions부터 확인합니다
기존 OpenAI SDK 앱은 base_url과 모델 이름을 바꾸는 방식으로 첫 연결 부담을 줄일 수 있습니다. 공식 문서에서 확인되는 호환 범위는 Chat Completions, Completions, Embeddings 중심입니다.
OpenAI SDK로 챗봇, 요약기, 임베딩 검색을 이미 만들어 둔 코드라면 Xinference를 별도 API 서버처럼 두고 endpoint만 바꿔 비교할 수 있습니다. 이 단계에서 볼 것은 기존 호출 흐름이 로컬 endpoint까지 이어지는지입니다.
"OpenAI compatible"이라는 표현은 범위를 넓게 오해하기 쉽습니다. Assistants API, 파일 처리, 호스팅된 벡터 저장소, 특정 도구 호출 경험까지 같은 방식으로 된다고 쓰면 과장입니다. 기준은 공식 문서에서 확인되는 Chat Completions, Completions, Embeddings 연결입니다.
첫 테스트에서 남길 항목은 많지 않습니다.
| 확인 항목 | Xinference에서 볼 부분 | 주의할 점 |
|---|---|---|
| 채팅 API | `/v1` base_url과 실행 중인 모델 이름 | 모델별 응답 품질과 컨텍스트 길이는 별도 확인 |
| 임베딩 | Embeddings API 연결 | 검색 품질은 임베딩 모델 선택에 좌우됨 |
| 기존 앱 이식 | OpenAI SDK 설정 교체 | 전체 OpenAI 제품군 호환으로 확대 해석하지 않기 |
| 사내 PoC | endpoint, 모델 캐시, metrics | 인증과 네트워크 경계는 별도 설계 필요 |
Docker에서는 포트와 캐시부터 고정합니다
Docker로 Xinference를 띄울 때는 공식 이미지 `xprobe/xinference`, 컨테이너 9997 포트, 호스트 포트 매핑, all-interface host binding, `XINFERENCE_HOME` 또는 모델 캐시 볼륨을 함께 기록합니다. 운영에 가까운 테스트에서는 supervisor `/metrics`, worker metrics, tokens/s, status code, first-token latency도 같은 표에 남깁니다.
팀 PoC에서는 Docker가 조건을 고정하기 쉽습니다. 실행 환경을 남기고, 모델 캐시를 볼륨으로 유지하고, GPU 서버 한 대에서 같은 요청을 반복할 수 있습니다. GPU 이미지를 쓰려면 CUDA와 NVIDIA Container Toolkit 조건을 맞춰야 하며, v2.0 이후 CUDA 이미지의 최소 CUDA 버전은 12.9로 문서화되어 있습니다.
포트 매핑은 초반에 적어 둬야 합니다. 문서 예시는 컨테이너 내부 9997을 호스트 9998로 매핑합니다. 이 경우 호스트에서 접근하는 endpoint는 `http://127.0.0.1:9998`이고, OpenAI 호환 base_url도 `http://127.0.0.1:9998/v1`처럼 호스트 포트 기준으로 맞춥니다. all-interface host binding을 빠뜨리면 호스트에서 컨테이너 내부 서비스에 접근하지 못할 가능성이 있습니다.
한국 사용자에게는 모델 파일 위치가 자주 걸립니다. `XINFERENCE_HOME`은 기본적으로 사용자 홈의 `.xinference` 아래에 모델과 로그 등 필요한 파일을 둡니다. Hugging Face, ModelScope, CSGHub 중 어떤 소스에서 모델을 받을지, 캐시를 어디에 둘지, 토큰과 미러링 정책을 어떻게 둘지 정해야 반복 테스트가 흔들리지 않습니다.
v2.10.0의 운영 항목은 metrics 확인과 이어집니다. metrics 문서는 supervisor의 `/metrics`와 worker exporter를 설명하고, 요청 수, 응답 수, 상태 코드, tokens/s, input/output token counter, first-token latency를 확인할 수 있다고 안내합니다. 이 지표가 없으면 "느리다"는 말을 모델 문제, 네트워크 문제, GPU 병목으로 나눌 근거가 부족합니다.
어떤 팀과 작업에 맞는가
Xinference는 OpenAI SDK를 이미 쓰는 코드베이스에서 로컬 LLM endpoint 이식성을 확인하거나, 사내망·온프레미스 모델 서빙 PoC를 시작할 때 잘 맞습니다. 개인 채팅 앱 하나가 목적이면 더 가벼운 로컬 모델 실행 도구가 나을 때도 있습니다.
한국 독자에게 필요한 판단 근거는 국내 인기 순위보다 코드 이식성, 내부망 테스트, GPU/CPU 배포 비교입니다. 확인된 출처 안에서 말할 수 있는 사용 이유도 이 범위에 머뭅니다.
Xinference를 후보로 놓을 만한 상황은 아래와 같습니다.
- OpenAI Python SDK를 쓰는 챗봇, 요약기, RAG 앱의 endpoint 교체 테스트
- 사내망 LLM 서빙에서 외부 API 호출을 줄일 여지가 있는지 보는 PoC
- 임베딩 모델과 채팅 모델을 같은 API 서버 계층에서 비교하는 실험
- GPU 서버 한 대에서 시작해 worker/supervisor 또는 Kubernetes로 확장성을 확인하는 팀
- Dify, LangChain, LlamaIndex 같은 앱·워크플로 계층 뒤에 모델 서빙 백엔드를 두려는 경우
Kubernetes는 localhost와 Docker 테스트가 정리된 뒤에 봐도 늦지 않습니다. Helm repo 추가와 `helm install xinference xinference/xinference` 경로가 문서화되어 있다는 점은 로컬 실험 이후 클러스터 배포까지 이어질 수 있다는 신호로 읽으면 됩니다.
도입 전에 멈춰서 확인할 리스크
Xinference가 상용 API보다 항상 싸거나 빠르다고 단정하면 위험합니다. 모델 라이선스, GPU·CPU 조건, 캐시 디스크, 네트워크 다운로드 정책, 인증, metrics, rollback 계획을 확인하지 못했다면 production-like 사용으로 넓히지 않는 편이 맞습니다.
v2.10.0에는 OIDC/Keycloak SSO, 감사 로그, rate limiting 같은 기능이 들어갔습니다. 그 사실만으로 외부 인터넷 공개가 준비됐다고 보기는 어렵습니다. 공식 인증 문서가 Simple OAuth2 시스템을 experimental로 표시한다는 점도 같이 봐야 합니다.
팀 환경에서는 reverse proxy, TLS, 방화벽, API key 보관, secret 관리, 감사 로그 보존 기간을 따로 설계해야 합니다. 모델 endpoint는 비용과 데이터가 동시에 걸리는 서비스라서 인증이 어설프면 GPU 자원 낭비와 데이터 노출 위험이 같이 커집니다.
라이선스도 분리해서 봐야 합니다. 저장소 코드가 Apache-2.0이라는 사실은 확인됐지만, 사용자가 내려받아 실행하는 개별 모델의 라이선스, 가중치 사용 조건, 데이터셋 제한은 별도 검토 대상입니다. 특히 상업 서비스나 사내 업무 데이터 처리에서는 이 구분이 중요합니다.
개인 개발 환경에서 Xinference GitHub local LLM serving OpenAI compatible API를 실험한다면 Xinference는 검토 목록에 올릴 수 있습니다. 운영 담당 없이 큰 모델을 외부 공개 endpoint로 띄우려는 계획은 작은 proof-of-work와 내부망 제한을 끝낸 뒤에 다시 보는 편이 낫습니다.
자주 묻는 질문
Q. Xinference는 Ollama나 vLLM과 무엇이 다른가?
A. Xinference는 여러 모델 유형을 REST API, Web UI, CLI, 분산 배포 흐름으로 묶는 서빙 프레임워크입니다. vLLM은 Xinference 안에서 선택할 수 있는 백엔드 후보 중 하나입니다. API 서버, 모델 lifecycle, metrics까지 같은 체크리스트에 넣는 PoC라면 Xinference 쪽이 맞습니다.
Q. Xinference 설치 후 첫 테스트는 어떤 순서가 안전한가?
A. `pip install "xinference[all]"`로 설치하고 `xinference-local`을 띄운 뒤, 작은 모델 하나를 launch합니다. OpenAI SDK의 `base_url`은 `http://127.0.0.1:9997/v1`로 지정해 Chat Completions 요청을 보냅니다. 이때 endpoint 연결, model UID, 종료 절차까지 함께 확인합니다.
Q. 기존 OpenAI SDK 앱은 base_url만 바꾸면 바로 쓸 수 있나?
A. 첫 연결 테스트는 base_url과 모델 이름 교체로 줄어듭니다. 공식 문서상 확인되는 범위는 Chat Completions, Completions, Embeddings 중심입니다. Assistants API 같은 OpenAI 플랫폼 기능은 요구 기능별로 지원 여부를 따로 대조해야 합니다.
Q. Docker로 실행할 때 9997과 9998 포트는 어떻게 봐야 하나?
A. Xinference 기본 서비스 포트는 9997이고, Docker 문서 예시는 컨테이너 9997을 호스트 9998에 매핑하는 패턴을 보여 줍니다. 이 매핑을 쓰면 호스트의 OpenAI 호환 base_url은 `http://127.0.0.1:9998/v1`처럼 호스트 포트 기준으로 맞춰야 합니다.
Q. 로컬 GPU가 없어도 Xinference를 테스트할 수 있나?
A. 작은 모델과 CPU 또는 환경에 맞는 백엔드로 연결 흐름을 확인하는 테스트는 가능합니다. vLLM처럼 처리량을 기대하는 경로는 Linux와 CUDA GPU 조건을 확인해야 합니다. 큰 모델 성능 비교 결과는 GPU, 메모리, 모델 크기에 따라 크게 달라집니다.
Q. 사내망에서 쓰기 전에 무엇을 먼저 봐야 하나?
A. 모델 파일 출처와 캐시 위치, `XINFERENCE_HOME`, 네트워크 다운로드 정책, API key 보관, 인증 방식, TLS, reverse proxy, audit log, `/metrics` 지표를 확인해야 합니다. v2.10.0 보안 기능이 늘었더라도 공식 인증 문서의 experimental 표기는 따로 확인해야 합니다.
Q. Xinference 도입을 건너뛸 조건은 무엇인가?
A. 데스크톱에서 모델 하나와 채팅하려는 목적이면 더 가벼운 도구가 맞을 때가 있습니다. 모델 라이선스, GPU 비용, 캐시 디스크, 인증, metrics, 장애 복구, 버전 rollback을 맡을 사람이 없다면 production-like 사용으로 넓히지 않는 편이 낫습니다.
함께 읽으면 좋은 글
- Context7 GitHub 추천: AI 코딩 도구에 최신 문서를 넣는 MCP 서버 — GITHUB 추천
- OpenAgent GitHub 추천: Qwen-VL까지 붙은 개인 AI 에이전트 실험법 — GITHUB 추천
- GitHub 추천: coleam00/Archon, AI 코딩을 반복 가능한 워크플로로 만들기 — GITHUB 추천
- Pipecat v1.3.0 추천: 음성 AI 에이전트를 multi-agent 구조로 확장하는 법 — GITHUB 추천
- Google Tunix GitHub 추천: Gemma를 reasoning 모델처럼 학습하는 실험실 — GITHUB 추천
참조 링크
- xorbitsai/inference — 공식 저장소로 프로젝트 목적, README, 통합 도구, 웹 UI의 약식 star 표시를 확인하는 기본 원문
- Release v2.10.0 — 2026-06-05T23:00:21Z 릴리스 시점과 v2.10.0 운영·보안 변경점 확인
- GitHub API repository metadata for xorbitsai/inference — 9,342 stars, pushed_at, Apache-2.0 license 확인
- Installation - Xinference — pip 설치와 vLLM, llama.cpp, SGLang, MLX 등 백엔드별 extra 확인
- Using Xinference — OpenAI SDK base_url, 모델 목록, Chat Completions·Completions·Embeddings 사용 흐름 확인
- Xinference Docker Image — Docker 이미지, GPU 조건, 9998:9997 포트 매핑, `-H 0.0.0.0`, 캐시 볼륨 확인
- Environments Variables - Xinference — `XINFERENCE_ENDPOINT`, `XINFERENCE_HOME`, 모델·로그 저장 위치 확인
- Metrics - Xinference — supervisor `/metrics`, worker metrics, tokens/s, latency, status code 지표 확인
- Simple OAuth2 System (experimental) — 보안 기능 소개 시 experimental 인증 안내를 함께 확인하기 위한 근거
- Xinference on Kubernetes — Helm repo와 Kubernetes 설치 경로 확인
- xinference on PyPI — PyPI 패키지명과 2.10.0 배포 확인