Continuum Router 및 API¶

Backend.AI GO는 로컬 네트워크를 위한 AI API 게이트웨이 역할을 합니다.

Continuum Router란 무엇인가요?¶

Continuum Router는 내부에서 "교통 정리" 역할을 하는 컴포넌트입니다. 로컬 하드웨어에서 실행 중인 모델이나 클라우드 API를 통해 연결된 모델 등, 모든 AI 모델에 접근할 수 있는 단일 통합 진입점을 제공합니다.

더 자세한 기술 문서는 docs.continuum.lablup.ai를 참고하세요.

OpenAI 호환 API¶

Backend.AI GO는 OpenAI API 표준과 동일한 방식의 API를 제공합니다. 즉, OpenAI를 지원하는 모든 애플리케이션에서 백엔드 주소만 Backend.AI GO로 바꿔서 바로 사용할 수 있습니다.

• 엔드포인트: http://localhost:39080/v1 (기본값)
• 인증: 선택 사항 (설정에서 구성 가능)

예시: curl을 사용한 호출¶

curl http://localhost:39080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3",
    "messages": [{"role": "user", "content": "안녕!"}]
  }'

요청 타임아웃과 헬스 체크¶

API > Health에는 서로 연관된 두 종류의 설정이 있습니다. 라우터가 각 백엔드를 얼마나 자주 확인하는지, 그리고 요청을 포기하기까지 얼마나 기다리는지입니다.

Backend.AI GO는 설치 직후부터 timeouts: 섹션을 라우터가 읽는 구조 그대로 기록합니다. 따라서 새로 설치한 상태에서도 라우터 자체 기본값이 아니라 여기 적힌 예산으로 동작합니다.

timeouts:
  connection: 10s
  request:
    standard:          # 스트리밍이 아닌 요청
      first_byte: 30s
      total: 300s
    streaming:         # 스트리밍(SSE) 요청
      first_byte: 120s
      chunk_interval: 30s
      total: 600s
    image_generation:
      first_byte: 60s
      total: 180s
  health_check:
    timeout: 4s
    interval: 5s

알아 두면 좋은 네 가지가 있습니다.

• 실제로 동작하는 first_byte는 스트리밍 쪽 하나뿐입니다. 스트리밍 응답의 첫 청크를 기다리는 시간을 제한하며, 라우터가 이 값을 강제합니다. 첫 청크가 도착한 뒤부터는 chunk_interval이 이어받습니다. 추론 모델은 첫 토큰까지 1분을 넘기는 일이 흔해서 기본값을 120초로 잡았습니다.
• 나머지 두 first_byte는 아무 일도 하지 않습니다. 스트리밍이 아닌 응답은 답변 전체가 만들어진 뒤 한 번에 전달됩니다. 그래서 standard와 image_generation에서는 첫 바이트까지의 시간이 곧 전체 생성 시간이고, 실제로 적용되는 예산은 total 하나뿐입니다. 두 항목 모두 파일에는 여전히 있어야 해서 그냥 지울 수는 없고, 값을 바꿔도 아무 영향이 없습니다. 기본값 그대로 두세요. 스트리밍이 아닌 요청이 중간에 끊긴다면 올려야 할 값은 total입니다.
• health_check는 직접 편집하는 값이 아니라 자동으로 만들어집니다. 라우터는 실제 헬스 체크 주기와 개별 검사 타임아웃을 health_checks 섹션이 아니라 timeouts.health_check에서 읽습니다. 그래서 앱은 파일을 쓸 때마다 검사 주기와 타임아웃 값으로 이 블록을 다시 만듭니다. 라우터는 타임아웃이 주기보다 짧아야 한다고 요구하므로, 두 값이 같으면 타임아웃을 1초 줄이고 사용자가 지정한 주기를 그대로 사용합니다.
• 한도는 라우터가 검사합니다. 스트리밍이 아닌 요청의 total이 9분을 넘거나, 스트리밍 total이 20분을 넘거나, 스트리밍 first_byte가 8분을 넘거나, 청크 간격이 1초에서 60초를 벗어나거나, 연결 타임아웃이 15초를 넘으면 라우터가 설정 파일을 읽을 때 거부하고 아예 시작하지 않습니다. Backend.AI GO도 저장 전에 같은 한도를 검사하므로, 한도를 넘는 값은 라우터가 시작하지 못하는 형태로 나중에 드러나지 않고 이 화면에서 해당 항목 이름과 함께 거부됩니다.

로컬 소켓 위치¶

같은 컴퓨터 안에서 Backend.AI GO는 TCP 포트가 아니라 Unix 도메인 소켓으로 라우터와 통신합니다. 이 소켓 파일과 로컬 모델 서버의 소켓은 모두 짧은 사용자별 런타임 디렉터리에 만들어집니다.

디렉터리는 앱을 시작할 때 한 번 정해지며, 현재 라우터 소켓 경로는 API > 일반의 소켓 경로에서 확인할 수 있습니다. 자동으로 선택되는 위치에는 사용자 이름이 들어가지 않습니다. Unix 소켓 경로는 103바이트까지만 허용되는데, 이전 버전은 홈 디렉터리가 포함된 애플리케이션 데이터 디렉터리 아래에 소켓을 만들었기 때문에 macOS 계정 이름이 16바이트(한글 6글자) 이상이면 라우터가 path must be shorter than SUN_LEN 오류로 시작하지 못했고, 모델 서버는 11바이트부터 조용히 TCP로 전환되었습니다.

후보 디렉터리는 소유자 전용 권한으로 생성되고 사용 전에 검사됩니다(심볼릭 링크가 아닌지, 본인 소유인지, 그룹이나 다른 사용자가 접근할 수 없는지, 실제로 테스트 소켓을 바인딩할 수 있는지). 검사에 실패한 디렉터리는 로그에 이유를 남기고 건너뛰며 다음 후보로 넘어갑니다. 기존 애플리케이션 데이터의 sockets/ 디렉터리는 마지막 후보입니다. 이전 위치에 남은 소켓 파일은 시작 시 한 번 정리됩니다.

사용할 수 있는 디렉터리가 하나도 없으면(예: /tmp에 쓸 수 없거나 샌드박스 빌드의 컨테이너 경로가 너무 긴 경우) 라우터는 루프백 TCP 포트에 바인딩된 상태로 시작하고, 알림으로 그 이유를 알려 줍니다. 이 대체 바인딩은 아래 외부 접속 허용 설정과 무관하게 항상 127.0.0.1로 열립니다. 꺼둔 API 서버를 대신 공개하는 것이 아니라 로컬 소켓 하나를 대신하는 자리이기 때문에, 외부 접속을 켜 두어도 네트워크에 노출되지 않습니다. 이 모드에서는 모든 로컬 프로세스가 루프백 포트에 접근할 수 있으므로 라우터 Admin API 토큰이 유일한 보호 수단입니다. 소켓 모드로 되돌리려면 설정 > 고급에서 더 짧은 소켓 디렉터리(62바이트 이하, 재시작 후 적용)를 지정하거나 /tmp를 쓰기 가능하게 하세요.

외부 접속 설정¶

기본적으로 API는 사용자의 컴퓨터(127.0.0.1)에서만 접근할 수 있습니다. 태블릿이나 다른 노트북 등 로컬 네트워크 내의 다른 기기에서 모델을 사용하고 싶다면:

1. API > 일반으로 이동합니다.
2. 외부 접속 허용(Allow External Access)을 활성화합니다.
3. 원격 클라이언트를 받기 전에 API > 보안과 API > 액세스 키에서 인증을 구성합니다.
4. 다른 앱에서 내 컴퓨터의 로컬 IP 주소(예: http://192.168.1.10:39080/v1)를 사용합니다.