두 개의 API 표면

이 장에서 배우는 것 하이퍼팀즈(HyperTeams)가 바깥에 내주는 두 개의 문, 각각이 무엇을 열어주는지, 그리고 켜기 전에 반드시 이해해야 할 것.

API·엔드포인트가 처음이라면 API란 무엇인가를 먼저 보세요.

여기서부터 성격이 바뀝니다

앞의 12장은 화면에서 쓰는 법이었습니다. 이 파트는 다른 프로그램이 이 컴퓨터를 부르게 만드는 이야기입니다.

그러려면 문을 열어야 하고, 문을 열기 전에 무엇이 열리는지 알아야 합니다.

문은 정확히 두 개입니다

graph TD
  A["/api/* 전체"] --> B["/api/v1<br/>HyperTeams 자신의 REST"]
  A --> C["/api/ai<br/>모델 — OpenAI 호환"]
  A --> D["그 밖의 모든 /api/*<br/>대시보드 전용"]
  B --> B1["Bearer 열쇠"]
  C --> C1["Bearer 열쇠"]
  D --> D1["브라우저 쿠키<br/>바깥에서 못 부름"]

이 둘 말고는 바깥에서 부를 수 없습니다. 화면이 쓰는 라우트들은 로그인한 브라우저의 쿠키로만 열립니다.

기본값은 꺼짐입니다

가장 중요한 성질입니다.

켠 적 없는 설치에서는 이 경로들이 아예 존재하지 않습니다 — 404입니다.

401(권한 없음)이 아니라 404(없음)라는 게 의도된 것입니다. 켜지 않은 시스템은 API가 있다는 사실조차 광고하지 않습니다.

열쇠가 곧 대시보드 비밀번호입니다

여기가 이 장의 핵심입니다.

API 열쇠는 별도로 발급되는 값이 아니라 대시보드 비밀번호 그 자체입니다.

이 설계에는 결과가 따라옵니다.

결과 1 — 비밀번호가 없으면 켤 수 없습니다

비밀번호를 설정하지 않은 설치는 대시보드 자체가 인증 없이 도는 전제(내 컴퓨터에서만 접속)로 서 있습니다. 거기에 "아무 값이나 통과하는 API"를 더하면 그 전제가 깨지는 순간 두 배로 열립니다. 그래서 아예 켜지지 않습니다.

결과 2 — 열쇠가 퍼지는 곳이 늘어납니다

비밀번호를 Bearer로 쓰기 시작하면 그 값이 이런 데 붙습니다.

하나가 새면 대시보드가 통째로 열립니다. 터널에서 "주소를 아는 누구나 시도할 수 있다"고 한 것과 같은 이야기인데, 이쪽은 값이 여러 곳에 복사된다는 점이 다릅니다.

그래서 켤 때 자문할 것: 이 열쇠가 붙을 곳을 전부 셀 수 있습니까? 셀 수 없으면 아직 켤 때가 아닙니다.

모델 표면은 3단계입니다

REST는 켜짐/꺼짐 둘이지만, 모델 쪽은 얼마나 여는지를 고릅니다.

inference가 열어주는 목록은 정해져 있습니다.

이 목록 밖은 inference에서 404입니다. 모델을 내려받거나 서버를 재시작하는 관리 동작은 full에서만 열립니다.

inference부터 시작하세요. 다른 프로그램에 모델을 빌려주는 목적이라면 추론만으로 충분하고, full은 그 프로그램이 내 모델 서버를 관리할 수 있게 하는 것입니다. 최소 권한이 여기도 그대로 적용됩니다.

두 base 주소

모델 쪽은 안내되는 주소가 둘인데, 헷갈리기 쉬워서 정리합니다.

/api/ai 아래가 상류 모델 서버의 루트와 1:1로 대응하기 때문에 이렇게 됩니다. 상류 자신이 "루트 아래 /v1에 OpenAI 표면"이라 그 중첩이 그대로 따라옵니다.

⚠ 중첩이라서 경로가 범위를 강제하지 않습니다. …/api/ai/v1을 안내했다고 해서 그 아래로만 갈 수 있는 게 아닙니다 — 범위를 정하는 것은 경로가 아니라 inference / full 모드입니다.

⋯ → 전역 설정 → 일반 → API 입니다. 두 API 표면을 켜고 끄는 자리가 여기이고, 대시보드 비밀번호를 정하기 전에는 그것부터 하라고 안내합니다 — 그 비밀번호가 열쇠이기 때문입니다.

켜는 순서

4번이 중요합니다. 한 번 성공하면 그다음은 복사입니다. 처음부터 여러 곳에 붙이면 어디가 틀렸는지 못 찾습니다.

명세는 어디에 있나

이 시스템은 OpenAPI 3.1 명세를 스스로 내놓습니다. 다만 그 명세는 공개 표면이 아니라 대시보드 게이트 뒤에 있습니다.

• 로그인한 브라우저에서 문서 화면으로 봅니다
• 외부 도구에 필요하면 내려받아 건네면 됩니다

명세가 비밀은 아니지만, 이 시스템이 무엇을 열어 두었는지 광고할 이유도 없습니다. 그래서 열쇠 없이 읽히는 자리에 두지 않았습니다.

자주 하는 오해

"API 키를 따로 발급받는 것 아닌가요?"

아닙니다. 대시보드 비밀번호가 그대로 열쇠입니다. 그래서 비밀번호를 바꾸면 그 값을 넣어둔 모든 곳을 함께 고쳐야 합니다.

"켜두면 편하니까 둘 다 켜두면 되지 않나?"

쓰지 않는 표면은 끄는 게 맞습니다. 켜져 있다는 것은 열쇠 하나로 그쪽도 열린다는 뜻입니다. 모델만 쓸 거면 REST는 꺼두세요.

"로컬에서만 쓸 건데도 이게 문제가 되나요?"

localhost로만 쓴다면 위험은 훨씬 작습니다. 다만 터널을 여는 순간 같은 열쇠가 인터넷에서 통합니다. 터널과 API를 함께 켤 때 비밀번호의 강도가 실제로 중요해집니다.

확인

1. 켜지 않은 시스템에서 API를 부르면 401이 아니라 404가 나오는 이유는?

2. API 열쇠가 무엇이고, 그래서 무엇을 조심해야 합니까?

3. 모델 표면에서 inference와 full의 차이는?

먼저 업무를 외부에서 시켜봅니다 → REST로 업무 시키기