One API란
One API는 오픈 소스 대규모 모델 API 관리 및 릴레이 시스템입니다. 다양한 모델 공급업체의 인터페이스를 표준 OpenAI API 형식으로 통합하여, 클라이언트가 동일한 API Base와 액세스 토큰으로 여러 상위 채널을 호출할 수 있도록 합니다.
이 프로젝트는 OpenAI 및 Azure OpenAI, Anthropic Claude, Google Gemini, Mistral, Doubao, Wenxin Yiyan, Tongyi Qianwen, iFlytek Spark, ChatGLM, Tencent Hunyuan, Moonshot AI, DeepSeek, Ollama, Cohere, Groq, Cloudflare Workers AI, xAI 등 다양한 서비스를 지원합니다.
컴플라이언스 안내: One API를 사용할 때는 OpenAI 이용 약관과 관련 법률 및 규정을 준수해야 하며, 불법적인 용도로 사용해서는 안 됩니다. 중국 지역 대중을 대상으로备案되지 않은 생성형 인공지능 서비스를 제공하지 마십시오.
핵심 기능
통합 인터페이스: OpenAI 호환 API 형식으로 다양한 대규모 모델에 액세스합니다.
다중 채널 및 로드 밸런싱: 여러 상위 채널을 구성할 수 있으며, 채널을 지정하지 않으면 자동으로 로드 밸런싱을 수행합니다.
스트리밍 출력: stream 모드를 지원하여 타자기 방식의 응답을 구현할 수 있습니다.
토큰 관리: 만료 시간, 한도, 허용 IP 범위 및 액세스 가능한 모델을 설정할 수 있습니다.
채널 관리: 채널 일괄 생성, 모델 목록 설정, 채널 그룹 및 모델 매핑을 지원합니다.
한도 및 결제: 한도 상세 정보, 사용자 그룹, 채널 그룹, 배율 및 달러 한도 표시를 지원합니다.
안정성: 실패 시 자동 재시도, 다중 서버 배포, Redis 캐시 및 데이터베이스 연결 설정을 지원합니다.
관리 확장: 시스템 액세스 토큰으로 관리 API를 호출할 수 있어 소스 코드를 수정하지 않고도 관리 기능을 확장할 수 있습니다.
사용자 시스템: 이메일, Feishu, GitHub 및 WeChat 공식 계정 등의 로그인 및 가입 방식을 지원합니다.
UI 사용자 지정: 시스템 이름, Logo, 바닥글, 홈페이지, 소개 페이지 및 테마를 사용자 지정할 수 있습니다.
Docker로 빠르게 배포
데이터 디렉터리 준비
SQLite는 빠른 테스트 또는 낮은 동시성 배포에 적합합니다. 먼저 쓰기 가능한 데이터 디렉터리를 준비합니다. 데이터베이스와 로그는 이 디렉터리에 저장됩니다.
mkdir -p /home/ubuntu/data/one-apiOne API 시작
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-p 3000:3000의 왼쪽 포트는 호스트 시스템의 포트이므로 필요에 따라 변경할 수 있습니다. 시작한 후 http://localhost:3000/에 접속합니다.
초기 사용자 이름은 root, 초기 비밀번호는 123456입니다.
중요: 처음 root로 로그인한 후에는 반드시 기본 비밀번호를 즉시 변경해야 합니다.
Docker Hub 이미지를 가져올 수 없는 경우 justsong/one-api를 ghcr.io/songquanpeng/one-api로 바꿀 수 있습니다. 컨테이너 시작에 실패하면 프로젝트 이슈 기록을 참고하여 --privileged=true 추가를 시도할 수 있습니다.
MySQL로 배포
동시성이 높은 경우 README에서는 SQL_DSN을 설정하고 SQLite를 계속 사용하지 않을 것을 명확히 권장합니다. 데이터베이스 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사용자 이름, 비밀번호, 주소 및 포트를 실제 데이터베이스 매개변수로 바꾸십시오. MySQL이 호스트 시스템에서 실행 중인 경우 네트워크 환경에 따라 --network="host"를 추가하여 컨테이너가 호스트 데이터베이스에 액세스하도록 할 수 있습니다.
Docker Compose 사용
저장소는 Docker Compose 시작 방식을 제공하며, 현재 안내에서는 MySQL을 사용하고 데이터를 ./data/mysql 디렉터리에 저장합니다.
docker-compose up -d
docker-compose ps소스 코드에서 수동 배포
직접 빌드하려면 Node.js, npm 및 Go 환경을 준비한 다음 프런트엔드와 백엔드를 차례로 빌드합니다.
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--port는 수신 대기 포트를 지정하며 기본값은 3000입니다. --log-dir는 로그 디렉터리를 지정합니다. 또한 --version으로 버전을 확인하거나 --help로 도움말을 확인할 수 있습니다.
기본 설정 완료
One API 관리 페이지를 열고 root 계정으로 로그인한 다음 기본 비밀번호를 변경합니다.
채널 페이지로 이동하여 해당 공급업체 유형을 선택하고 상위 API Key를 추가합니다.
상위 서비스의 기능에 따라 채널에서 지원하는 모델 목록과 그룹을 설정합니다.
토큰 페이지로 이동하여 클라이언트에서 사용할 액세스 토큰을 생성합니다.
필요에 따라 토큰의 한도, 유효 기간, 허용 IP 범위 및 액세스 가능한 모델을 설정합니다.
One API는 기본적으로 바로 사용할 수 있습니다. 기타 설정은 관리 인터페이스, 환경 변수, .env 파일 또는 명령줄 매개변수를 통해 완료할 수 있습니다. .env를 사용할 때는 저장소의 .env.example을 참고하여 이름을 .env로 변경하십시오.
OpenAI 호환 인터페이스 사용
클라이언트의 API Base를 One API 배포 주소로, API Key를 방금 생성한 One API 토큰으로 설정해야 합니다. 구체적인 Base URL 형식은 클라이언트에 따라 다르며, OpenAI 공식 라이브러리의 경우 README에 다음과 같은 설정 형식이 제시되어 있습니다.
OPENAI_API_KEY="sk-xxxxxx"
OPENAI_API_BASE="https://<HOST>:<PORT>/v1"요청은 먼저 One API에 도착한 다음 One API를 통해 OpenAI, Azure 또는 기타 모델 채널로 전달됩니다. 인터페이스 형식이 다른 상위 서비스의 경우 One API가 릴레이에 필요한 요청 본문 및 응답 본문 변환을 처리합니다.
기존 클라이언트와 함께 사용
사용자 지정 OpenAI 인터페이스 주소를 지원하는 대부분의 클라이언트는 연결할 수 있습니다. ChatGPT Next Web을 예로 들면 먼저 클라이언트 컨테이너를 실행합니다.
docker run --name chat-next-web -d -p 3001:3000 yidadaa/chatgpt-next-web그런 다음 클라이언트 페이지에서 One API 인터페이스 주소와 One API 토큰을 입력합니다. 포트는 One API가 사용하는 3000과 충돌하지 않아야 합니다.
ChatGPT Web도 환경 변수를 통해 One API에 연결할 수 있습니다.
docker run --name chatgpt-web -d -p 3002:3002 -e OPENAI_API_BASE_URL=https://openai.example.com -e OPENAI_API_KEY=sk-xxx chenzhaoyu94/chatgpt-web예시 도메인과 토큰을 자신의 설정으로 바꾸십시오.
고급 설정 팁
채널 지정 또는 로드 밸런싱 활성화
기본적으로 채널을 지정하지 않은 요청은 여러 사용 가능한 채널 사이에서 로드 밸런싱됩니다. 관리자가 생성한 토큰은 토큰 뒤에 채널 ID를 추가하여 이번 요청을 특정 채널에서 처리하도록 강제할 수도 있습니다.
Authorization: Bearer ONE_API_KEY-CHANNEL_ID일반 사용자가 생성한 토큰은 이 방식으로 채널 ID를 지정할 수 없습니다.
모델 매핑은 신중하게 사용
모델 매핑을 사용하면 사용자가 요청한 모델을 다른 모델로 리디렉션할 수 있습니다. 그러나 README에서는 필요하지 않은 경우 모델 매핑을 설정하지 말 것을 안내합니다. 활성화하면 요청 본문이 그대로 전달되지 않고 다시 구성되므로, 아직 공식적으로 지원되지 않는 일부 필드가 정상적으로 전달되지 않을 수 있습니다.
Redis 캐시 사용
REDIS_CONN_STRING을 설정하면 One API는 Redis를 캐시로 사용합니다.
REDIS_CONN_STRING=redis://default:redispw@localhost:49153데이터베이스 액세스 지연 시간이 매우 낮다면 Redis를 활성화할 필요가 없습니다. 캐시로 인해 데이터 동기화 지연이 발생할 수 있기 때문입니다. 센티넬 또는 클러스터 모드에서는 이 변수를 노드 목록으로 설정하고 REDIS_PASSWORD 및 REDIS_MASTER_NAME과 함께 사용할 수 있습니다.
데이터베이스 연결 최적화
데이터베이스 연결은 다음 환경 변수로 조정할 수 있습니다.
SQL_MAX_IDLE_CONNS: 최대 유휴 연결 수, 기본값100.SQL_MAX_OPEN_CONNS: 최대 열린 연결 수, 기본값1000.SQL_CONN_MAX_LIFETIME: 연결 최대 수명, 기본값60분.BATCH_UPDATE_ENABLED=true: 데이터베이스 일괄 업데이트 집계를 활성화합니다. 연결 수 과다 문제를 완화할 수 있지만 한도 업데이트가 지연됩니다.BATCH_UPDATE_INTERVAL=5: 일괄 업데이트 집계 간격을 설정하며 단위는 초입니다.
Error 1040: Too many connections이 발생하면 SQL_MAX_OPEN_CONNS를 적절히 줄이고 일괄 업데이트 활성화 여부를 검토할 수 있습니다.
세션, 시간 초과 및 프록시 설정
SESSION_SECRET: 고정 세션 키를 설정합니다. 재시작 후에도 로그인한 사용자의 Cookie가 계속 유효합니다.RELAY_TIMEOUT: 릴레이 요청 시간 초과를 설정하며 단위는 초입니다.RELAY_PROXY: 릴레이 요청이 지정된 프록시를 통해 상위 API에 액세스하도록 합니다.USER_CONTENT_REQUEST_TIMEOUT: 사용자가 업로드한 콘텐츠 다운로드의 시간 초과를 설정합니다.USER_CONTENT_REQUEST_PROXY: 이미지 등 사용자가 업로드한 콘텐츠의 다운로드 프록시를 설정합니다.
채널 모니터링 설정
채널 잔액을 정기적으로 업데이트하고 채널 사용 가능 여부를 테스트할 수 있습니다.
CHANNEL_UPDATE_FREQUENCY=1440
CHANNEL_TEST_FREQUENCY=1440
POLLING_INTERVAL=5앞의 두 변수의 단위는 분이고, POLLING_INTERVAL의 단위는 초이며 일괄 작업 시 요청 간격을 제어하는 데 사용됩니다.
다중 서버 배포 구성
다중 서버 배포에서는 더 이상 로컬 SQLite에 의존할 수 없습니다. 모든 노드는 동일한 MySQL 데이터베이스에 연결하고 일관된 세션 설정을 유지해야 합니다.
모든 서버에 동일한
SESSION_SECRET을 설정합니다.모든 서버가
SQL_DSN을 통해 동일한 MySQL 데이터베이스에 연결되도록 설정합니다.슬레이브 서버에
NODE_TYPE=slave을 설정합니다. 설정하지 않으면 기본값은 마스터 서버입니다.SYNC_FREQUENCY를 사용하여 데이터베이스에서 설정을 정기적으로 동기화합니다.슬레이브 서버에서
FRONTEND_BASE_URL을 설정하여 페이지 요청을 마스터 서버로 리디렉션할 수 있습니다.각 슬레이브 서버에 Redis를 배포하고
REDIS_CONN_STRING을 설정하여 캐시 유효 기간 동안 데이터베이스 액세스를 줄일 수 있습니다.마스터 서버의 데이터베이스 액세스 지연 시간이 높은 경우 Redis와 정기 동기화도 활성화하는 것이 좋습니다.
SESSION_SECRET=random_string
SQL_DSN=root:123456@tcp(database:3306)/oneapi
NODE_TYPE=slave
SYNC_FREQUENCY=60
FRONTEND_BASE_URL=https://openai.example.com
REDIS_CONN_STRING=redis://default:redispw@localhost:49153Nginx 및 HTTPS 구성
프로덕션 환경에서는 Nginx를 One API의 리버스 프록시로 사용할 수 있습니다. 응답 시간이 긴 모델의 경우 읽기 타임아웃을 적절히 늘려야 합니다.
server {
server_name openai.example.com;
location / {
client_max_body_size 64m;
proxy_http_version 1.1;
proxy_pass http://localhost:3000;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_cache_bypass $http_upgrade;
proxy_set_header Accept-Encoding gzip;
proxy_read_timeout 300s;
}
}Ubuntu에서는 Certbot을 사용하여 HTTPS를 신청하고 구성할 수 있습니다.
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot
sudo certbot --nginx
sudo service nginx restart자주 발생하는 문제 해결
할당량 부족 메시지가 표시됨: 계정 할당량 외에도 토큰 자체의 할당량 한도를 확인해야 합니다.
사용 가능한 채널이 없다는 메시지가 표시됨: 사용자 그룹, 채널 그룹 및 채널에서 지원하는 모델 목록을 확인합니다.
현재 그룹의 부하가 포화됨: 일반적으로 업스트림 채널이 429를 반환했다는 의미입니다.
클라이언트에 Failed to fetch가 표시됨: 인터페이스 주소, API Key 및 HTTPS 구성을 확인합니다. HTTPS 페이지에서 HTTP 요청을 보내면 브라우저가 차단할 수 있습니다.
채널 테스트에서 invalid character가 반환됨: 업스트림에서 올바른 JSON이 아닌 HTML을 반환했을 수 있으며, 배포 서버 IP 또는 프록시 노드가 Cloudflare에 의해 차단되었을 수도 있습니다.
업그레이드 후 데이터 손실이 걱정됨: 정상적인 업그레이드로 MySQL 데이터가 손실되지는 않습니다. SQLite는
one-api.db를 영구 보존할 수 있도록 데이터 볼륨을 올바르게 마운트해야 합니다.
맺음말
One API는 여러 모델 공급업체를 OpenAI 호환 호출 방식으로 통합하고 채널, 토큰, 할당량 및 사용자를 중앙에서 관리하는 데 적합합니다. 개인 사용자 또는 낮은 동시성 환경에서는 Docker와 SQLite로 시작할 수 있으며, 높은 동시성 및 다중 서버 환경에서는 공유 데이터베이스를 사용하고 지연 시간에 따라 Redis를 신중하게 도입해야 합니다. 사용을 시작하기 전에 기본 비밀번호를 변경하고 HTTPS를 구성하며 데이터를 영구 보존하고, 서비스가 관련 약관과 법률 및 규정을 준수하는지 확인하세요.
이 프로젝트는 MIT 라이선스로 오픈 소스이지만 README에서는 페이지 하단에 저작자 표시와 프로젝트 링크를 유지하도록 요구합니다. 저작자 표시를 제거하려면 먼저 허가를 받아야 합니다. 자세한 내용은 One API GitHub 저장소에서 확인할 수 있습니다.