One-API

One-API

One-API는 표준 OpenAI API 형식으로 여러 대형 언어 모델(LLM)에 접근할 수 있게 해주는 오픈소스 LLM API 게이트웨이예요. OpenAI, Azure OpenAI, Anthropic Claude, Google Gemini, Mistral, DeepSeek, Coze, Ollama 등 다양한 업체의 모델을 하나의 통일된 OpenAI 형식 API로 묶어서 제공해서, 별도 개발 없이도 여러 모델을 한 곳에서 관리하고 라우팅할 수 있어요. 토큰 관리, 채널(채널) 관리, 로그, 사용량 집계 같은 기능을 갖추고 있고, Docker 기반으로 쉽게 배포해서 자체 호스팅할 수 있어요. Go로 작성되었고 MIT 라이선스로 공개되어 있어요.

출처: 문서

본문

One-API는 안정 버전과 preview 버전, 그리고 alpha 버전의 Docker 이미지를 공식 제공해요. 안정/미리보기 버전은 justsong/one-api 또는 ghcr.io/songquanpeng/one-api, alpha 버전은 justsong/one-api-alpha 또는 ghcr.io/songquanpeng/one-api-alpha에서 받을 수 있어요.

Docker로 배포하기

SQLite를 사용하는 가장 기본적인 배포 명령이에요.

# SQLite를 사용하는 배포 명령:
docker run --name one-api -d --restart always -p 3000:3000 -e TZ=Asia/Shanghai -v /home/ubuntu/data/one-api:/data justsong/one-api
# MySQL을 사용하는 배포 명령, 위 명령에 `-e SQL_DSN="root:123456@tcp(localhost:3306)/oneapi"`를 추가하면 돼요. 데이터베이스 연결 파라미터는 직접 수정해야 하고, 수정 방법이 궁금하면 아래 환경 변수 부분을 참고해요.
# 예시:
docker run --name one-api -d --restart always -p 3000:3000 -e SQL_DSN="root:123456@tcp(localhost:3306)/oneapi" -e TZ=Asia/Shanghai -v /home/ubuntu/data/one-api:/data justsong/one-api

여기서 -p 3000:3000의 첫 번째 3000은 호스트(서버)의 포트라서 필요에 따라 바꿀 수 있어요. 데이터와 로그는 호스트의 /home/ubuntu/data/one-api 디렉터리에 저장되는데, 이 디렉터리가 존재하고 쓰기 권한이 있는지 확인하거나 적절한 경로로 바꿔주세요. 만약 시작이 실패하면 --privileged=true를 추가해 보세요. 이미지를 받을 수 없다면 justsong/one-api 대신 ghcr.io/songquanpeng/one-api를 사용하면 돼요. 동시 요청이 많다면 반드시 SQL_DSN을 설정해야 해요.

Docker Compose로도 배포할 수 있어요.

# 현재 MySQL로 구동할 수 있으며, 데이터는 ./data/mysql 폴더에 저장돼요.
docker-compose up -d

# 배포 상태 확인
docker-compose ps

수동으로 배포할 수도 있어요. GitHub Releases에서 실행 파일을 받거나 소스 코드에서 직접 빌드하면 돼요.

git clone https://github.com/songquanpeng/one-api.git

# 프론트엔드 빌드
cd one-api/web/default
npm install
npm run build

# 백엔드 빌드
cd ../..
go mod download
go build -ldflags "-s -w" -o one-api

실행은 이렇게 해요.

chmod u+x one-api
./one-api --port 3000 --log-dir ./logs

그리고 http://localhost:3000/에 접속해서 로그인하면 돼요. 최초 계정은 사용자 이름 root, 비밀번호 123456이에요. root로 처음 로그인한 뒤에는 반드시 기본 비밀번호를 바꿔야 해요.

사용 방법과 API 라우팅

사용 방법은 간단해요. 채널(channel) 페이지에서 API Key를 추가하고, 토큰 페이지에서 접근 토큰을 새로 만들면 돼요. 이후 이 토큰으로 One-API에 접근하는 방식은 OpenAI API와 완전히 동일해요.

OpenAI API를 쓰는 각종 프로젝트에서 API Base를 One-API 배포 주소로, API Key를 One-API에서 생성한 토큰으로 설정하면 돼요. 예를 들어 OpenAI 공식 라이브러리에서는 이렇게 설정해요.

OPENAI_API_KEY="sk-xxxxxx"
OPENAI_API_BASE="https://<HOST>:<PORT>/v1"

One-API는 요청을 이렇게 라우팅해요. 사용자가 One-API가 발급한 키로 요청하면, One-API가 중계해서 OpenAI, Azure, 기타 OpenAI 형식 채널로 보내거나, 요청체와 응답체를 변환해서 비-OpenAI 형식 채널로 보내는 구조예요.

토큰 뒤에 채널 ID를 붙이면 특정 채널로 처리하도록 지정할 수 있어요. 예: Authorization: Bearer ONE_AP...ID. 단, 관리자 계정이 만든 토큰만 채널 ID를 지정할 수 있어요. 채널 ID를 지정하지 않으면 로드밸런싱(부하 분산) 방식으로 여러 채널을 자동으로 나눠서 사용해요.

주요 기능

  • 다양한 모델 지원: OpenAI ChatGPT 계열(Azure OpenAI API 포함), Anthropic Claude(AWS Claude 지원), Google PaLM2/Gemini, Mistral, DeepSeek, Coze, Ollama, Groq, xAI, DeepL 등 수많은 모델을 지원해요.
  • 채널(채널) 관리: 여러 채널을 일괄 생성하고, 채널마다 모델 목록을 설정할 수 있어요. 로드밸런싱으로 여러 채널에 부하를 분산하고, 실패 시 자동 재시도도 지원해요.
  • 토큰 관리: 토큰의 만료 시간, 한도(quota), 허용 IP 범위, 접근 허용 모델을 설정할 수 있어요. 환불(교환) 코드 관리와 일괄 생성/내보내기도 가능해요.
  • 사용자 및 그룹: 사용자 그룹과 채널 그룹을 나누고 그룹마다 다른 배율(multiplier)을 적용할 수 있어요. 사용자 초대 보상, 달러 단위 한도 표시도 지원해요.
  • 로그와 사용량: 사용량 내역(quota detail)을 확인할 수 있고, 채널 잔액을 주기적으로 갱신하거나 채널 가용성을 검사할 수 있어요.
  • 그 외 설정: 시스템 이름/로고/푸터 커스터마이징, Markdown/HTML 홈페이지, 메시지 푸시 연동, Cloudflare Turnstile 사용자 검증, 테마 전환(THEME 환경 변수), 관리 API를 통한 확장 등을 지원해요.

환경 변수

One-API는 .env 파일에서 환경 변수를 읽을 수 있어요. .env.example 파일을 참고해서 .env로 이름을 바꿔 사용하면 돼요. 주요 환경 변수는 다음과 같아요.

  • REDIS_CONN_STRING: 이 값을 설정하면 Redis를 캐시로 사용해요. 예: REDIS_CONN_STRING=redis://default:***@localhost:49153
  • SESSION_SECRET: 고정된 세션 키를 사용해서 서버 재시작 후에도 로그인 쿠키가 유효하게 해요. 예: SESSION_SECRET=random_string
  • SQL_DSN: SQLite 대신 지정한 데이터베이스(MySQL 또는 PostgreSQL)를 사용해요. 예: SQL_DSN=root:123456@tcp(localhost:3306)/oneapi
  • FRONTEND_BASE_URL: 페이지 요청을 지정한 주소로 리다이렉트해요. 예: FRONTEND_BASE_URL=https://openai.justsong.cn
  • NODE_TYPE: 노드 타입을 지정해요. master 또는 slave, 설정하지 않으면 master예요.
  • SYNC_FREQUENCY: 캐시 사용 시 데이터베이스와 동기화 빈도(초). 기본 600초.
  • CHANNEL_UPDATE_FREQUENCY: 채널 잔액을 주기적으로 갱신(분 단위). 설정하지 않으면 갱신 안 함.
  • CHANNEL_TEST_FREQUENCY: 채널 가용성을 주기적으로 검사(분 단위). 설정하지 않으면 검사 안 함.
  • GLOBAL_API_RATE_LIMIT: 전역 API 속도 제한. 단일 IP 3분 내 최대 요청 수, 기본 180.
  • GLOBAL_WEB_RATE_LIMIT: 전역 Web 속도 제한. 단일 IP 3분 내 최대 요청 수, 기본 60.
  • TIKTOKEN_CACHE_DIR: 시작 시 다운로드하는 토큰 인코딩 데이터를 캐시할 디렉터리. 오프라인 환경에서 유용해요.
  • THEME: 시스템 테마 설정, 기본 default.
  • INITIAL_ROOT_TOKEN: 설정하면 시스템 최초 시작 시 이 값을 가진 root 사용자 토큰을 자동 생성해요.

멀티 노드 배포

여러 서버에 분산 배포하려면 다음을 지켜요.

  1. 모든 서버의 SESSION_SECRET을 같은 값으로 설정해요.
  2. 반드시 SQL_DSN을 설정하고, SQLite 대신 MySQL을 사용해서 모든 서버가 같은 데이터베이스에 연결해요.
  3. 모든 서브(보조) 서버는 NODE_TYPE을 slave로 설정해요. 설정하지 않으면 기본이 마스터 서버예요.
  4. SYNC_FREQUENCY를 설정하면 서버가 주기적으로 데이터베이스에서 설정을 동기화해요. 원격 데이터베이스일 때는 이 옵션과 Redis를 권장해요.
  5. 서브 서버는 FRONTEND_BASE_URL로 페이지 요청을 마스터 서버로 리다이렉트할 수 있어요.
  6. 서브 서버마다 Redis를 따로 설치하고 REDIS_CONN_STRING을 설정하면, 캐시가 만료되기 전에는 데이터베이스 접근 없이 처리해서 지연을 줄일 수 있어요.

명령줄 파라미터

  • --port <port_number>: 서버가 수신할 포트 번호, 기본 3000. 예: --port 3000
  • --log-dir <log_dir>: 로그 폴더 지정. 설정하지 않으면 작업 디렉터리의 logs 폴더에 저장돼요. 예: --log-dir ./logs
  • --version: 시스템 버전을 출력하고 종료해요.
  • --help: 명령 사용법과 파라미터 설명을 보여줘요.

더 알아보기 (Learn more)