Onyx 딥다이브
— 어떤 LLM이든 꽂아 쓰는 40개 커넥터 셀프호스팅 AI 플랫폼

1프로젝트 한줄 요약

Onyx는 어떤 LLM이든 연결 가능한 셀프호스팅 AI 챗 플랫폼으로, 40개 이상의 데이터 소스 커넥터 + RAG(검색증강생성) + 에이전트 시스템을 결합한 엔터프라이즈급 오픈소스 솔루션입니다.

쉽게 비유하면 "회사 내부 데이터를 다 연결해서 ChatGPT처럼 대화할 수 있는 시스템을 직접 서버에 설치해 쓰는 것"입니다. GitHub 스타: 30k(2026-06-04 기준), 기여자: 198+.

2왜 주목받는가

경쟁 제품 비교

3기술 스택 전체 지도

백엔드 (Python 67.2%)

프론트엔드 (TypeScript 27.6%)

인프라

4아키텍처 심화 분석

핵심 설계 패턴

① 하이브리드 검색 (Hybrid Search)

벡터 검색(의미 기반)과 키워드 검색(BM25)을 동시에 수행하고 결과를 합칩니다. "의미를 이해하는 검색"과 "정확한 단어를 찾는 검색"을 동시에 돌려서 최적의 결과를 뽑아내는 방식입니다.

② 커넥터 아키텍처 (Strategy 패턴)

# 커넥터 공통 인터페이스 (간소화)
class BaseConnector:
    def load(self) -> Iterator[Document]:
        """전체 데이터 로드 (초기 인덱싱)"""
        ...
    def poll(self, start_time) -> Iterator[Document]:
        """변경분만 가져오기 (증분 인덱싱)"""
        ...
    def slim(self) -> Iterator[DocumentId]:
        """ID만 가져오기 (삭제 감지용)"""
        ...

40개 커넥터가 공통 인터페이스를 구현합니다. 새 데이터 소스를 추가하려면 이 인터페이스만 맞추면 됩니다. load/poll/slim 3가지 모드로 전체 인덱싱·증분 인덱싱·삭제 감지를 각각 처리합니다.

③ LLM 루프 3계층 파이프라인

process_message(검증·세션·권한) → run_chat_loop_with_state_containers(컨텍스트·도구·스트리밍) → run_llm_step(프롬프트 구성·LLM 호출·응답 파싱)으로 계층이 명확히 분리됩니다.

④ Docker-out-of-Docker (DooD) 코드 인터프리터

code-interpreter:
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock  # 호스트 Docker 소켓 공유
  user: root  # Docker 소켓 접근 필요

컨테이너 내부에서 또 컨테이너를 만드는 게 아니라, 호스트의 Docker 소켓을 마운트하여 형제 컨테이너를 생성합니다. 보안과 성능의 균형을 맞춘 코드 실행 패턴입니다.

5디렉토리 구조 해부

6학습 포인트 (기술별)

FastAPI + SSE 스트리밍

FastAPI로 대규모 API 서버를 설계하는 방법, Uvicorn 워커 프로세스 관리, SSE(Server-Sent Events)로 채팅 응답을 실시간 전달하는 구현을 배웁니다.

# SSE 스트리밍 응답 패턴
from fastapi.responses import StreamingResponse

async def chat_stream(request):
    async def generate():
        async for chunk in llm_loop.run():
            yield f"data: {chunk.json()}\n\n"
    return StreamingResponse(generate(), media_type="text/event-stream")

RAG 파이프라인 구축

문서 청킹 전략(고정/재귀/의미 기반), 벡터 임베딩 생성과 인덱싱(Vespa), 하이브리드 검색 구현(벡터+BM25+리랭킹), 지식 그래프로 RAG 정확도 향상시키기, 컨텍스트 윈도우 압축을 익힙니다.

커넥터 시스템 설계

전략 패턴으로 다양한 데이터 소스 통합, load/poll/slim 3가지 인덱싱 모드의 차이, OAuth2 토큰 관리와 API Rate Limiting 처리, 증분 인덱싱(Incremental Indexing) 구현을 배웁니다.

Docker 멀티서비스 아키텍처

11개 서비스를 Docker Compose로 오케스트레이션하는 방법, 헬스체크 설정과 서비스 간 의존성 관리, docker-bake.hcl로 멀티플랫폼 이미지 빌드, DooD 패턴을 배웁니다.

LLM 통합 + 엔터프라이즈 기능

LiteLLM으로 여러 LLM 프로바이더를 하나의 인터페이스로 통합하는 법, RBAC(역할 기반 접근 제어), SSO(OIDC/SAML/OAuth2), 문서 레벨 권한 미러링, 멀티테넌시 설계를 공부합니다.

7하드웨어 / 시스템 요구사항

최소 사양 (개발/테스트)

권장 사양 (프로덕션)

Docker 서비스별 메모리

8직접 해볼 수 있는 실습 과제

docker compose up -d
# http://localhost:3000 에서 관리자 계정 생성

9관련 기술 심화 학습 로드맵

1주차: 기초 세팅 & 아키텍처 이해

Onyx 로컬 배포 및 전체 서비스 구조 파악, Docker Compose 11개 서비스 역할 매핑, PostgreSQL + Redis + Vespa 기본 개념

2주차: RAG 핵심 개념

문서 청킹 전략(고정/재귀/의미 기반), 벡터 임베딩 원리(Word2Vec → Sentence Transformers), Vespa로 하이브리드 검색 실습, OpenSearch BM25 검색

3주차: 백엔드 심화

FastAPI 비동기 패턴 + SSE 스트리밍, Celery 태스크 큐로 비동기 인덱싱, SQLAlchemy 관계형 모델링, LiteLLM 멀티 프로바이더 통합

4주차: 프론트엔드 심화

Next.js 16 App Router + React 19 서버 컴포넌트, Zustand 상태 관리 패턴, SWR 데이터 페칭 + 실시간 업데이트, Radix UI 컴포넌트 커스터마이징

5주차: 커넥터 & 에이전트

커넥터 아키텍처 분석 및 커스텀 커넥터 개발, MCP(Model Context Protocol) 이해 및 도구 제작, 에이전트 시스템 설계 패턴, 지식 그래프 구축 기초

6주차: 프로덕션 & 운영

Kubernetes 배포 실습, Terraform IaC로 클라우드 인프라 구성, Sentry/Prometheus/Langfuse 모니터링, SSO/RBAC 엔터프라이즈 보안

10핵심 키워드 사전

11참고 링크

• GitHub 레포 (onyx-dot-app/onyx)
• 공식 문서
• 공식 사이트
• Vespa 문서
• OpenSearch 문서
• LiteLLM 문서
• MCP 프로토콜 스펙
• FastAPI 공식 문서
• Next.js 공식 문서
• Zustand 문서
• RAG 개념 설명 (Anthropic)