umm 관리자 가이드

기준 버전 v0.71.6. 화면을 쓰는 사람을 위한 안내는 사용자 가이드에 있습니다. 이 문서의 화면은 모두 v0.71.6 을 실제로 띄워 1440x900 에서 찍은 것이며, 데이터는 가짜입니다. 환경 변수 표는 internal/config/config.go 에서, API 의 메서드와 경로는 internal/httpapi/server.go 의 라우트 등록에서 읽었습니다.

1. 구성 요소

실행 중에는 패키지 저장소나 CDN 에 접근하지 않습니다. 폐쇄망 반입은 이미지 하나면 됩니다.

2. 설치

릴리즈 자산은 umm-v0.71.6.tar.gz 와 SHA256SUMS 입니다.

2-1. 이미지 반입

sha256sum -c SHA256SUMS
./scripts/load-offline.sh umm-v0.71.6.tar.gz      # = gzip -dc umm-v0.71.6.tar.gz | docker load
docker image inspect umm:v0.71.6 --format ''

2-2. compose 로 띄우기

저장소의 compose.yaml 이 PostgreSQL 17 과 umm 을 함께 올립니다. 비밀값은 그 파일의 개발용 값을 그대로 쓰지 말고 아래처럼 바꿔 넣습니다. 암호화 키는 연결망 밖의 승인된 절차로 만들고(openssl rand -base64 32) shell history·compose 파일·티켓·Git 에 남기지 마세요.

# 예시 값 — 모두 가짜입니다
export POSTGRES_PASSWORD='change-me-db-password'
export BOOTSTRAP_ADMIN_PASSWORD='change-me-admin-password'
export ENCRYPTION_KEY="$(openssl rand -base64 32)"

cat > compose.override.yaml <<'EOF'
services:
  postgres:
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
  umm:
    image: umm:v0.71.6
    environment:
      POSTGRES_DSN: "postgres://umm:${POSTGRES_PASSWORD}@postgres:5432/umm?sslmode=disable&pool_max_conns=16"
      BOOTSTRAP_ADMIN: admin
      BOOTSTRAP_ADMIN_PASSWORD: ${BOOTSTRAP_ADMIN_PASSWORD}
      ENCRYPTION_KEY: ${ENCRYPTION_KEY}
EOF

docker compose up -d
curl -s http://127.0.0.1:8080/readyz     # {"status":"ready"}

이미 PostgreSQL 이 있다면 umm 만 docker run 합니다. 필요한 환경 변수는 아래 표의 필수 네 개뿐입니다.

docker run -d --name umm --restart unless-stopped -p 8080:8080 \
  -e POSTGRES_DSN='postgres://umm:change-me-db-password@postgres.internal:5432/umm?sslmode=require&pool_max_conns=16' \
  -e BOOTSTRAP_ADMIN='admin' \
  -e BOOTSTRAP_ADMIN_PASSWORD='change-me-admin-password' \
  -e ENCRYPTION_KEY='<openssl rand -base64 32 의 출력>' \
  umm:v0.71.6

PostgreSQL 사용자는 대상 데이터베이스에 schema·table·extension(pgcrypto, citext, pg_trgm)을 만들 권한이 있어야 합니다. 마이그레이션은 기동 시 트랜잭션으로 자동 적용됩니다.

2-3. 최초 관리자 계정

BOOTSTRAP_ADMIN / BOOTSTRAP_ADMIN_PASSWORD 로 첫 관리자가 만들어집니다. 이미 그 계정이 DB 에 있으면 재시작해도 비밀번호를 덮어쓰지 않습니다. 로그인 뒤 순서대로:

1. 서비스 관리자 → 일반: 서비스 이름, 공개 URL, Asia/Seoul 같은 IANA 시간대.
2. 키 · 권한: 허용 API/MCP 스코프, 기본 만료, 회전 중첩, 남용 방지 한도 확인.
3. 필요할 때만 Keycloak SSO 를 저장하고 연결 시험 뒤 활성화.
4. 필요할 때만 AI Gateway 를 저장하고 임베딩 품질 측정에서 🟢 확인.
5. Dream Layer 는 Gateway 확인 뒤 기능과 자동 생성을 각각 켭니다.
6. 검토 프로세스에서 실제로 승인이 필요한 작업만 켭니다. 꺼져 있으면 승인 단계는 생기지 않습니다.

3. 설정

3-1. 환경 변수

internal/config/config.go 와 internal/observability/observability.go 가 읽는 전부입니다. 나머지 정책은 모두 관리자 화면에서 PostgreSQL 에 저장되며 재시작이 필요 없습니다.

필수 넷 중 하나라도 비면 기동하지 않고 로그에 invalid startup configuration 이 남습니다.

브라우저 변경 요청의 Origin 은 공개 URL 또는 신뢰 proxy 로 확인한 현재 요청과 scheme·host·port 가 모두 같아야 합니다. HTTPS 서비스에 http:// Origin 은 거부됩니다. Proxy 는 외부에서 온 forwarding header 를 지우고 자신이 확인한 값을 적도록 구성하세요.

3-2. 관리자 화면의 설정

왼쪽 메뉴 순서대로. 각 절의 자세한 값은 아래 부록에 있습니다.

4. 계정과 권한

역할은 셋입니다. 사용자는 bootstrap 관리자가 만들거나 Keycloak SSO 첫 로그인으로 생깁니다 — 사용자 생성 API 는 없습니다. 로컬 계정을 더 두려면 SSO 를 붙이거나 관리자가 DB 에서 만들어야 합니다.

SSO 를 쓰면 Keycloak SSO 화면의 관리자 그룹·팀장 그룹으로 역할이 매핑됩니다.

공간 안의 권한(보기·편집·관리)은 공간 소유자가 이 공간 함께 쓰기에서 줍니다. 보기도 댓글은 쓸 수 있습니다.

개인 API·MCP 키는 사용자가 스스로 만들되 키 · 권한 화면의 허용 스코프 안에서만 고를 수 있습니다. 현재 스코프: notes:read notes:write spaces:read dreams:read approvals:write webhooks:write metrics:read ai:assist. ai:assist 만이 외부 Gateway 호출과 AI 쿼터 소비를 허용합니다.

5. 운영

5-1. 상태 점검

라우트 등록(internal/httpapi/server.go)에서 확인한 메서드입니다.

운영 현황의 실시간 협업 카드가 “폴백 폴링”이면 LISTEN 이 끊겨 1초 폴링 중이라는 뜻입니다. 협업은 되지만 DB 부하가 오르므로 umm_realtime_listener_up 에 알림을 걸어 두세요.

5-2. 로그

컨테이너 표준 출력에 JSON 한 줄씩(slog)입니다. docker compose logs -f umm. 요청 로그에는 requestId 가 있고 오류 응답에도 같은 값이 실리므로 사용자가 보낸 화면의 requestId 로 그 요청을 찾습니다.

5-3. 백업과 복구

상태는 전부 PostgreSQL 에 있습니다. 백업은 두 가지입니다 — DB 덤프와 ENCRYPTION_KEY. 키 없이는 덤프 속 OIDC·AI·Ptium·웹훅 secret 을 읽을 수 없습니다.

docker compose exec -T postgres pg_dump -U umm -Fc umm > umm-$(date +%F).dump

복구는 새 DB 에 pg_restore 한 뒤 같은 ENCRYPTION_KEY 로 umm 을 띄웁니다. scripts/restore-smoke.sh 가 이 순서를 카나리 데이터로 확인하는 절차입니다. 사용자 단위 백업은 캔버스의 내보내기 → Markdown 이며(그림은 담기지 않음), 같은 메뉴의 마크다운 가져오기로 돌아옵니다.

5-4. 업그레이드와 되돌리기

# 1. 백업
docker compose exec -T postgres pg_dump -U umm -Fc umm > before-upgrade.dump
# 2. 새 이미지 반입
gzip -dc umm-v0.71.6.tar.gz | docker load
# 3. 같은 환경 변수로 교체
docker compose up -d umm
curl -s http://127.0.0.1:8080/healthz

마이그레이션은 forward 로만 자동 적용됩니다. 되돌릴 때는 이전 이미지로 돌리기 전에 migrations/down/ 의 해당 스크립트를 새것부터 순서대로 직접 실행합니다 — 컬럼을 지우는 일이므로 자동으로는 절대 돌지 않습니다.

psql "$POSTGRES_DSN" -v ON_ERROR_STOP=1 -f migrations/down/027_note_attachments.down.sql

026 의 down 은 SELECT 1 뿐입니다 — 협업 로그에서 지운 본문 사본은 되돌려도 돌아오지 않습니다. 복수 인스턴스는 scripts/multi-instance-smoke.sh, 마이그레이션은 make migrate-dry-run 으로 미리 확인합니다.

5-5. 감사 로그

audit_logs 테이블에 영구 보존됩니다. 관리자의 설정 저장, 역할 변경, 공간 소유권 이전, webhook.pause 등이 남고 지우는 API 는 없습니다.

5-6. 웹훅

사용자가 개인 설정에서 만든 웹훅이 실패하고 있으면 여기서 보이고 멈추기로 active 만 내립니다. 자세한 것은 부록 9.

6. 장애 대응

7. 보안

• 바꿔야 하는 기본값 — compose.yaml 의 local-development-only·change-this-before-production·0123456789abcdef… 는 개발용입니다. 셋 다 바꾸고 나서 띄웁니다.
• 밖에 열면 안 되는 것 — PostgreSQL(5432), embeddings(11434). umm 의 8080 도 TLS proxy 뒤에만 둡니다. /api/v1/metrics 는 관리자 세션이나 metrics:read 키가 있어야 하지만 route 별 지연을 드러내므로 수집기에만 엽니다.
• Proxy — UMM_TRUSTED_PROXY_CIDRS 를 proxy 의 실제 대역으로만. 비우면 forwarding header 를 전부 버리므로 잠금·요청 제한이 proxy 주소 하나에 걸립니다. 0.0.0.0/0 은 클라이언트가 주소를 위조하게 합니다.
• 인증 연동 — Keycloak OIDC(부록 2). Client 는 Confidential, redirect URI 는 https://<umm>/api/v1/auth/oidc/callback. 로컬 로그인은 남용 방지의 잠금 규칙을 따릅니다(부록 4-1).
• 키 — ENCRYPTION_KEY 는 백업과 함께 별도 비밀 저장소에. 회전은 부록 8. API 키는 사용자가 만들되 스코프는 관리자가 허용한 범위 안이고, notes:read 만으로는 외부 AI 호출이 일어나지 않습니다.
• AI 로 나가는 것 — 생각 본문은 사용자가 Dream 분석에서 제외하거나 공간에서 AI Dream 분석을 끄면 어디로도 나가지 않습니다. 임베딩 API 키는 채팅 키와 따로이며 비우면 보내지 않습니다. 개인 설정의 내 AI 사용 내역이 사용자에게 같은 사실을 보여 줍니다.
• 감사 — 관리 행위는 전부 감사 로그에 남고 지울 수 없습니다.
• 자세한 위협 모델은 SECURITY.md.

부록 — 화면별 상세

아래는 각 관리자 화면의 값과 동작을 자세히 적은 것입니다. 번호는 위 표의 “부록 n” 과 같습니다.

부록 2. Keycloak OIDC SSO 연동

umm은 Keycloak OpenID Connect Discovery를 통해 복잡한 설정 없이 엔터프라이즈 SSO를 즉시 연동합니다.

1. Keycloak Client 생성:
   • Client type: OpenID Connect
   • Client authentication: ON (Confidential)
   • Standard Flow: ON
   • Valid redirect URIs: https://<umm-domain>/api/v1/auth/oidc/callback
2. 관리자 콘솔 설정 (/admin/oidc):
   • Keycloak SSO 활성화 스위치 ON
   • Issuer URL: https://keycloak.company.internal/realms/enterprise
   • Client ID & Client Secret: Keycloak에서 발급받은 자격증명 입력
   • 관리자 그룹/역할: umm-admins
   • 팀장 그룹/역할: umm-leads
3. 연결 시험:
   • 연결 시험 버튼을 클릭하여 OIDC Discovery 및 토큰 엔드포인트 도달 가능 여부를 실시간 검증합니다.

부록 3. Dream Layer & 야간 Scheduler 운영

Dream Layer는 사용자가 밤사이 휴식하는 동안 캔버스에 쌓인 생각들의 의미적 연관성을 분석하고 새로운 아이디어를 제안하는 핵심 백그라운드 엔진입니다.

생성 결과는 v0.6부터 캔버스에 즉시 삽입되지 않고 개인 Dream 검토함에 후보로 저장됩니다. 사용자가 채택할 때만 Dream 메모와 원본 연결선이 함께 생성되며, 기존 버전에서 이미 캔버스에 생성된 Dream은 업그레이드 시 채택 상태로 보존됩니다.

• 스케줄 설정:
  • 자동 생성 스위치 ON
  • 생성 시간: 기본 02:00 (사내 심야 시간대)
  • 생성 주기: 매일(Daily), 평일(Weekdays), 주말(Weekends), 특정 요일 선택, N일 간격
• 컨텍스트 & 256K 토큰 한도:
  • 최소 메모 개수: 2개 이상 메모가 있어야 분석 시작
  • 분석 범위: 최근 14일
  • 최대 응답 Token: 4K부터 최대 256K (262,144 tokens)까지 모델 사양에 맞춰 슬라이더로 조절
• 품질 기준선 (Quality Threshold):
  • 원본 두 개 이상에 대한 근거성, 적정 새로움, 구체성, 출처 범위를 결합한 내부 최소 점수
  • Quiet Mode: 가치가 확실하고 영감을 주는 의미 있는 Dream이 없을 경우 불필요한 노이즈 생성을 건너뜁니다.
• 선택 및 개인정보 보호:
  • 최근 Dream이 적은 적격 공간을 순환하고, 연결되지 않았으나 의미적으로 이어질 수 있는 메모 조합을 우선합니다.
  • 메모 또는 공간에서 AI 제외를 켜면 Scheduler 자격 계산, Dream 생성, AI Assist에서 모두 제외됩니다. 선택적 임베딩 모델을 설정했더라도 제외 콘텐츠는 Gateway로 전송하지 않고 서버 안의 로컬 vector만 사용합니다. 외부 임베딩 직전 note·space와 Gateway 설정을 다시 잠그고 응답 저장까지 유지하므로, 제외 설정이 먼저 적용되면 본문을 보내지 않고 임베딩이 먼저 시작되면 설정 변경이 호출 종료까지 기다립니다. 메모 하나만 제외된 공간도 Canvas와 범위 검색 전체가 같은 로컬 vector 공간을 사용해 일반 메모의 의미 검색 결과가 사라지지 않습니다. 원격 범위 검색은 space·membership·활성 note를 검색 완료까지 잠그며 제외·접근 회수 뒤의 검색어는 Gateway에 보내지 않습니다.
• 운영 지표:
  • 단순 생성 수 외에 검토 완료, 채택률, 편집·연결·확장 기반 유의미 활용률, 채택 Dream당 비용을 함께 확인합니다. 노출 수는 검토함을 불러온 횟수가 아니라 카드가 화면에 50% 이상 실제 표시된 경우만 반영됩니다.

부록 4. 내부 AI Gateway 연동

사내망 내부의 LLM Gateway (vLLM, Ollama, TGI, SGLang 등 OpenAI 호환 서버)를 연결합니다.

• Base URL: http://llm-gateway.internal:8000, .../v1, 전체 .../chat/completions 주소를 모두 사용할 수 있습니다.
• API Key: 내부 보안 게이트웨이 인증 토큰
• Timeout: 긴 추론 모델을 위해 최대 1800초까지 설정 가능. 이 값은 재시도를 모두 포함한 한 AI 작업의 전체 시간 예산이며, umm HTTP write timeout은 최대값보다 60초 길게 설정됩니다. 앞단 reverse proxy도 설정값보다 최소 60초 길게 응답 timeout을 구성하세요.
• 재시도: 0~5회. 전체 Timeout 안에서만 수행되므로 재시도마다 1800초가 다시 부여되지 않습니다.
• vLLM 추론 모델: 가능하면 서버에 모델별 --reasoning-parser를 설정합니다. 최종 본문 없이 reasoning/reasoning_content만 반환하거나 <think> 도중 출력 한도에 도달하면, 재시도가 1 이상일 때 umm이 비추론 모드로 다시 요청하고 최종 content만 사용합니다.
• 비용 통계 관리: 입력/출력 1M 토큰당 비용을 입력하면 관리자 대시보드에서 월간 예상 비용과 사용자당 비용을 실시간으로 추산합니다.
• 임베딩 모델: 비워 두면 외부 호출 없이 내장 로컬 임베딩(문자 n-gram)을 사용합니다. 내장 알고리즘은 어휘 중복을 재며 동의어를 인식하지 못합니다(라벨 데이터셋 기준 쌍별 정확도 4.2%). 지금 붙어 있는 백엔드가 어느 쪽인지는 아래 임베딩 품질 측정에서 바로 확인할 수 있습니다. 연관 생각·군집·Dream 품질을 실제로 올리려면 모델 설정이 사실상 필수입니다. 유사도 판정 기준은 v0.9.0부터 백엔드 분포에 맞춰 자동 조정되므로, 모델을 바꿔도 임계값을 손볼 필요가 없습니다. 모델 이름을 넣으면 같은 Gateway의 /v1/embeddings를 사용해 연관 생각·군집·검색의 의미 점수를 계산합니다. 모델이나 Gateway 주소를 바꾸면 endpoint fingerprint가 달라져 기존 생각이 열릴 때마다 점진적으로 다시 임베딩되며, 같은 모델명을 쓰는 서로 다른 제공자의 벡터도 섞여 비교되지 않습니다. 설정 변경 전에 시작한 이전 Gateway 응답은 저장 시점에 현재 설정과 다시 대조되어 폐기되므로 새 벡터를 뒤늦게 덮어쓰지 못합니다. 외부 호출과 vector 저장 동안에는 대상 note·space의 AI 제외 상태와 현재 Gateway 세대를 AI 전용 lease로 고정하므로 관리자가 제외를 저장한 뒤 캡처된 본문이 늦게 전송되는 경합도 없습니다. Gateway가 응답하지 않으면 전체 비교 집합을 로컬 임베딩으로 맞추고 5분간 로컬 회로 차단 상태를 유지해 Canvas를 열 때마다 원격 timeout이 반복되지 않습니다. 정책에 따른 로컬 전환은 장애로 세지 않아 회로 차단기를 열지 않습니다. 암호화된 API key를 현재 keyring으로 읽을 수 없는 경우에도 저장된 ciphertext를 Gateway 자격증명으로 시도하지 않고 즉시 로컬 provider로 닫습니다. 이 전체 로컬 정규화 pass도 장애가 난 원래 Gateway 설정 세대에 묶여 있으므로, 두 pass 사이에 저장한 새 Gateway의 vector를 덮지 않습니다. 임베딩과 Dream 오류 응답 본문 일부는 다국어 rune 경계를 보존해 관리자 오류와 로그가 유효한 UTF-8을 유지합니다. 설정을 저장하면 회로 차단 상태가 즉시 해제되어 새 설정을 확인합니다.

임베딩 Gateway를 따로 두기

임베딩과 채팅 모델이 같은 서버에 있을 이유는 없습니다. 큰 모델은 어딘가 강한 장비에 두고, 임베딩은 umm 옆에 작게 띄우는 편이 흔합니다 — compose.yaml의 embeddings 프로파일이 정확히 그 모양입니다.

채팅 API Key는 임베딩 주소로 따라가지 않습니다.

한 호스트에 발급된 키는 그 호스트의 자격증명입니다. 임베딩 키를 비워 뒀다는 이유로 채팅 키를 대신 보내면, 그 서버를 운영하는 사람에게 키를 건네주는 셈입니다. 인증이 필요 없는 임베딩 서버가 흔하므로 비움 = 보내지 않음입니다.

주소가 잘못되면 저장을 거부합니다. 조용히 무시하면 임베딩이 내장 알고리즘으로 돌아간 채, 설정 화면에는 저장된 값이 그대로 보이게 됩니다.

docker compose --profile embeddings up -d
docker compose exec embeddings ollama pull bge-m3

그 다음 임베딩 Gateway 주소에 http://embeddings:11434, 임베딩 모델에 bge-m3을 넣으면 됩니다. 채팅 모델 주소는 그대로 두어도 됩니다.

임베딩 품질 측정

관리자 → AI Gateway → 임베딩 품질 측정은 지금 설정된 백엔드로 라벨링된 한/영 문장쌍 22개를 직접 임베딩해 점수를 냅니다. 두 숫자만 보면 됩니다.

• 판별력 — 같은 뜻, 다른 표현의 평균에서 단어만 겹침의 평균을 뺀 값. 음수면 뜻보다 어휘를 높게 보고 있다는 뜻입니다.
• 쌍별 정확도 — 패러프레이즈와 어휘 함정을 짝지어 비교했을 때 올바른 순서를 매기는 비율. 임계값과 무관합니다.

세 가지 상태가 나옵니다.

결과는 백엔드별로 10분 캐시되며, 설정을 바꾼 뒤에는 다시 측정을 누르세요.

오프라인 임베딩 서버 띄우기

제대로 된 임베딩 모델을 umm 이미지에 넣으려면 추론 런타임을 링크해야 하고, 그러면 umm을 단일 이식 바이너리로 만드는 CGO_ENABLED=0 정적 빌드가 깨집니다. 대신 옆에 세우면 정적 빌드를 유지하면서도 완전 오프라인으로 돌릴 수 있습니다. 모델은 한 번만 받으면 이후에는 볼륨만 있으면 됩니다.

docker compose --profile embeddings up -d

컨테이너가 뜨면서 모델을 스스로 받습니다(UMM_EMBEDDING_MODEL로 변경 가능, 기본 bge-m3). 볼륨에 이미 있으면 다시 받지 않고, healthcheck는 서버 응답이 아니라 모델이 실제로 있는지를 확인합니다.

그다음 AI Gateway에서 자동으로 찾기를 누르면 주소와 모델 목록이 나옵니다. 모델을 고르고 연결 테스트로 확인한 뒤 저장하고, 임베딩 품질 측정에서 🟢가 뜨는지 보면 끝입니다.

자동 찾기가 조사하는 주소는 바이너리에 고정되어 있습니다(embeddings:11434, embeddings:8080, host.docker.internal:11434, 127.0.0.1:11434). 요청에서 주소를 받지 않습니다. 목록의 * 표시는 모델 이름으로 짐작한 것이며, 실제로 임베딩하는지는 연결 테스트가 확인합니다.

폐쇄망이라면 모델을 받아 둔 볼륨이나 ollama/ollama 이미지를 함께 반입하면 됩니다.

후보 모델 측정 결과

같은 데이터로 잰 값입니다. 임의의 OpenAI 호환 게이트웨이도 쓸 수 있습니다.

앞의 네 지표와 마지막 열이 서로 다른 순서를 매깁니다. 이건 측정 오류가 아니라 실제로 알아 둘 값입니다.

paraphrase-multilingual은 라벨 데이터 네 지표에서 모두 1위이고 크기도 절반 이하지만, umm의 종단 클러스터링 테스트(보안 3 + 자전거 3)에서 실패합니다. 인증 토큰 만료 시간을 24시간으로 정했다의 최근접 이웃으로 라이딩이 끝나면 스트레칭을 꼭 한다(0.32)를 고르기 때문입니다 — 같은 주제인 세션 쿠키...(0.23)보다 높게. 한 문장이 틀렸을 뿐인데 6개 메모 공간에서는 두 주제가 한 덩어리로 합쳐집니다.

즉 집계 점수가 높다고 특정 워크스페이스에서 더 나은 군집이 나오는 것은 아닙니다. 모델마다 틀리는 문장이 다르고, 메모 수가 적을수록 한 번의 실수가 결과를 지배합니다.

• 기본 권장은 bge-m3 입니다. 라벨 지표는 중간이지만 umm이 실제로 단언하는 종단 동작을 통과합니다.
• 한국어 비중이 높고 무관한 생각이 섞이는 쪽이 더 신경 쓰이면 판별력이 가장 높은 bona/bge-m3-korean.
• 디스크나 메모리가 빠듯하면 paraphrase-multilingual(562MB)도 실용적입니다. 다만 위 한계를 알고 쓰시고, 설정 후 실제 공간에서 연관 생각과 군집을 눈으로 확인하세요.

무엇을 고르든 임베딩 품질 측정에서 🟢가 뜨는지, 그리고 실제 공간에서 군집이 납득되는지 두 가지를 함께 보는 것이 가장 확실합니다.

지표가 뜻하는 것:

• 판별력 / 쌍별 정확도 — 뜻이 같은 문장쌍과 단어만 겹치는 문장쌍을 구별하는 능력.
• 주제 분리 / 최근접 동일 주제 — 라벨된 4개 주제 16문장에서, 같은 주제끼리 더 가까운지와 각 문장의 가장 가까운 이웃이 같은 주제인지. 연관 생각과 군집이 실제로 하는 일이 이쪽입니다.

직접 후보를 재려면:

UMM_EMBEDDING_TEST_URL=http://127.0.0.1:11434 \
UMM_EMBEDDING_TEST_MODEL=<모델명> \
go test ./internal/intelligence -run Gateway -v

종단 동작까지 확인하려면 (PostgreSQL 필요):

POSTGRES_DSN=... UMM_EMBEDDING_TEST_URL=http://127.0.0.1:11434 \
UMM_EMBEDDING_TEST_MODEL=<모델명> \
go test ./internal/store -run ClustersAndRelated -v

모델을 바꾸면 차원과 fingerprint가 달라져 기존 생각이 열릴 때마다 점진적으로 다시 임베딩됩니다. 유사도 판정 기준은 v0.9.0부터 백엔드 분포에 맞춰 자동 조정되므로 임계값을 손볼 필요는 없습니다.

부록 4-2. 유사도 기준 (/admin/intelligence)

저장하기 전에 재보기

기준은 표준편차 개수이므로 같은 숫자가 코퍼스에 따라 전혀 다른 일을 합니다. 그런데 무슨 일을 하는지 알아내는 방법은 저장하고 가서 보는 것뿐이었습니다. 저장하면 설치된 모든 캔버스가 한꺼번에 바뀌고, 바꾼 사람이 가장 늦게 압니다.

지금 값으로 재보기 는 아무것도 쓰지 않고 지금 있는 생각으로 두 기준을 나란히 재봅니다. 가장 큰 공간 다섯 개, 공간마다 400개까지를 표본으로 씁니다 — 비교는 공간 안에서 제곱으로 늘어나고 관리자가 기다리는 동안 돌기 때문입니다.

임베딩이 의미 비교에 부적합하다고 판정돼 있으면 캔버스는 위치로 묶으므로 군집 기준은 아무 일도 하지 않습니다. 그럴 때는 그 사실만 알려 주고 묶음 관련 네 줄은 아예 표시하지 않습니다 — 아무 일도 하지 않는다고 써 놓고 바로 밑에 묶음 개수를 적으면 방금 한 말을 도로 무르는 셈입니다. 연관 생각 쪽은 어느 백엔드에서나 채점되므로 그대로 나옵니다.

연관 생각·군집·연결 추천이 얼마나 과감할지를 정합니다. 거의 전부 분포 상대적입니다 — 백엔드마다 “가깝다”의 뜻이 다르므로, 이 공간의 유사도 분포에서 평균보다 몇 표준편차 위인지로 판단합니다. 모델을 바꿔도 손볼 필요가 없는 이유입니다.

두 하한을 낮춰도 넘을 수 없는 바닥

semantic_accuracy_bar 와 semantic_purity_bar 는 기본선 바로 아래에 있는 백엔드를 받아 주기 위한 것입니다. 한 언어·한 좁은 도메인만 쓰는 설치는 그럴 이유가 있습니다.

뜻보다 어휘를 높게 보는 백엔드는 두 값을 아무리 낮춰도 통과하지 못합니다. 의미 판정에는 세 번째 조건이 있고 — 판별력이 양수일 것 — 그건 설정이 아닙니다. 내장 char-gram 임베딩은 -0.25 입니다.

두 칸의 설명에 “내장 임베딩은 0.042”, “내장 임베딩은 0.188” 이라고 적혀 있어서 그 바로 아래로 낮추면 될 것처럼 보이지만, 그렇게 해도 달라지지 않습니다. 화면의 안내문이 같은 말을 하고 있습니다. 의미 기능을 실제로 켜는 방법은 임베딩 모델을 설정하는 것뿐입니다.

duplicate_similarity만 절대값인 것은 의도적입니다. 측정해 보면 실제 중복은 두 모델에서 0.943~0.986에 모이고 그다음 등급은 0.681에서 끊깁니다. 그리고 상대 기준은 여기서 실패합니다 — 중복이 많은 공간은 자기 분포가 통째로 올라가서, 중복이 가장 많을 때 중복이 특별해 보이지 않게 됩니다.

규모에 따른 경계

중복 검사는 모든 쌍을 비교하므로 제곱으로 자랍니다(1,024차원 실측: 1,000개 229ms · 2,000개 916ms · 10,000개 ≈ 23초). 한 공간에서 최근 1,000개까지만 비교하고, 그 위로는 오늘의 리뷰가 “공간이 커서 최근 생각까지만 비교했습니다”라고 말해 줍니다. 접어 둔 갈래의 생각은 별도로 최근 창과 교차 비교되므로, 오래전에 거절한 결정을 오늘 다시 써도 잡힙니다.

이 화면의 모든 항목은 의미를 재는 백엔드에서만 효과가 있습니다. 내장 임베딩에서는 연관 생각·군집·중복·연결 추천이 전부 꺼지고, 오늘의 리뷰가 backend-not-semantic으로 건너뛴 사실을 표시합니다.

부록 4-1. 남용 방지 (키 · 권한 → 남용 방지)

로그인 실패와 요청 폭주로부터 서비스를 보호하는 값들입니다. 저장 즉시 적용되며 재시작이 필요 없습니다.

롤링 배포 중 구버전 관리자 화면이 새 남용 방지 필드를 모른 채 보안 섹션을 저장해도, 서버는 생략된 로그인·API·AI 한도를 PostgreSQL의 최신 확정값에서 transaction으로 병합합니다. 명시한 값은 0을 포함해 그대로 적용하며 null이나 범위 밖 값은 저장 전에 거부하므로, 업그레이드 도중 운영자가 조정한 한도가 기본값으로 조용히 돌아가지 않습니다.

계정별 임계값을 주소별보다 높게 둔 이유는, 아이디를 아는 사람이 반복 실패를 일으켜 남의 계정을 마음대로 잠글 수 있는 상태를 피하기 위해서입니다. 로그인 성공은 해당 계정의 실패 횟수만 초기화하며, 같은 주소가 다른 계정에 누적한 실패 횟수는 유지되어 정상 계정 로그인으로 주소 제한을 우회할 수 없습니다.

로그인 실패 횟수와 하루 AI 사용량은 데이터베이스에서 관리합니다. 같은 주소·계정의 로컬 로그인은 모든 인스턴스가 공유하는 PostgreSQL 잠금 아래 비밀번호 확인과 실패 기록을 함께 처리하므로 병렬 요청도 설정한 실패 횟수를 초과해 검증되지 않습니다. 대화형 AI, 자동 Dream, 관리자 AI 평가는 실제 Gateway 호출 직전에 PostgreSQL에서 원자적으로 한도 자리를 선점하고 24시간 사용량으로 영속화하므로, 요청 취소·로그 저장 실패·여러 인스턴스의 동시 실행에도 하나의 상한이 적용됩니다. 분당 API 요청 한도는 인스턴스별로 계산되므로, 실효 상한은 설정값 × 인스턴스 수입니다.

허용 API/MCP scope에는 마이그레이션 009가 ai:assist를 자동 추가합니다. 이 scope는 선택한 생각을 외부 Gateway로 전송하고 AI 쿼터를 소비하는 /ai/assist에만 사용됩니다. 읽기 자동화에는 notes:read만, AI 발전 자동화에는 ai:assist만 또는 실제 작업에 필요한 두 scope를 함께 발급해 최소 권한을 유지하세요.

부록 7. Dream AI 평가 회귀

관리자 → AI 평가에서 최소 두 개의 입력 생각, 기대 단어와 금지 단어, Dream 유형을 저장합니다. 실행은 현재 AI Gateway와 prompt version을 그대로 사용하며 grounding, 기대/금지 단어, 구체성, 모델 응답 상태를 0~1 점수와 세부 항목으로 보존합니다. 모델·prompt·Gateway 설정을 바꾸기 전후에 같은 active case를 실행해 회귀를 확인하세요. Gateway 장애도 error run으로 남아 평가 이력이 사라지지 않습니다.

부록 8. Master-key 회전

새 키를 ENCRYPTION_KEY, 현재 키를 ENCRYPTION_KEY_PREVIOUS에 배치한 뒤 재시작합니다. 보안 화면에서 fallback 1개 이상, unreadable 0을 확인하고 현재 키로 회전을 실행합니다. 이 작업은 OIDC/AI secret, 웹훅 secret, 암호화 AI prompt를 한 트랜잭션으로 다시 암호화하며 enc: wrapper 도입 전 raw v1 AI prompt도 현재 wrapper·v2 형식으로 정규화합니다. 회전 전에 열어 둔 OIDC·AI Gateway 화면에서 마스킹된 값을 동시에 저장해도 서버가 같은 설정 lock 뒤 최신 암호문을 병합합니다. pending 0을 확인하고 새 백업을 만든 후에만 이전 키 환경변수를 제거합니다.

부록 8-2. Ptium 발표 연동이 실패할 때

사용자 화면에는 무엇을 해야 하는지가 적히고, 그중 절반은 “관리자에게 알려 주세요”입니다. 그 절반이 여기입니다.

묶음 제목을 AI가 짓기

발표 만들기에서 AI가 관여하는 곳은 여기 하나뿐이고, 그것도 제목뿐입니다.

• 켜야 동작합니다. 기본은 꺼져 있고, dream 설정의 모델이 없으면 옵션 자체가 아무 일도 하지 않습니다
• 묶음으로 만들어진 슬라이드만 대상입니다. 사람이 제목을 붙인 생각이나, 근거를 붙여 놓은 주장은 이미 자기 제목이 있습니다
• 한 번의 호출이고 최대 40묶음까지입니다. 수백 묶음짜리 덱이 프롬프트 하나에 공간 전체를 담지 않도록
• 본문은 절대 안 바뀝니다. 시험이 이걸 직접 확인합니다 — 제목만 바뀌고 lead·points·From 이 전부 그대로인지
• 실패하면 그냥 원래 제목입니다. 게이트웨이가 죽었다고 발표를 못 만들게 하지 않습니다
• 나가는 본문은 Complete 안에서 redaction 을 거칩니다. 호출자가 빠뜨릴 수 없도록 공유 진입점 안에 넣었습니다

돌아온 답이 문장이거나, 여러 줄이거나, JSON 객체면 쓰지 않고 원래 제목을 유지합니다. 이해 못 한 답으로 제목을 만들면 청중 앞 화면에서야 발견됩니다.

긴 발표를 부로 나누기

묶음 제목 과 별개 옵션이고, 역시 기본은 꺼져 있습니다.

• 슬라이드를 더하고, 옮기지 않습니다. 부 제목은 사람의 문장을 하나도 담지 않는 새 슬라이드이고, 원래 슬라이드는 자리·내용·출처 생각이 전부 그대로입니다
• 12장 미만이면 모델을 호출하지도 않습니다
• 부는 2~8개, 각 부에 최소 2장. 첫 부는 반드시 0번에서 시작해야 합니다
• 답이 조금이라도 어긋나면 통째로 버립니다. 제목과 달리 부는 서로 독립적이지 않아서, 하나를 버리면 앞 부의 범위가 조용히 늘어납니다 — 그러면 아무도 검토하지 않은 구성이 덱에 들어갑니다

슬라이드 위치는 앞에 끼워진 부 제목 수만큼 밀리고, 출처 지도는 그 뒤에 같은 목록으로 만들어지므로 “이 슬라이드가 어느 생각을 인용했는가”는 그대로 답할 수 있습니다.

색인이 사람의 경로에서 빠졌습니다 (v0.72.0)

ensureEmbeddings 의 호출자는 listNotes 하나뿐이었고, UpsertEmbedding 은 메모 생성·수정에서 동기로 불렸습니다. 즉 읽기도 쓰기도 임베딩 게이트웨이를 기다렸습니다.

실측: 호출당 2초 걸리는 게이트웨이에서 메모 3개 공간의 쓰기 3회 + 읽기 1회가 6.39초 → 0.18초.

• sweep은 5초 주기, 한 번에 최대 200개. 공간을 열거나 메모를 쓰면 그 공간을 먼저 보도록 알립니다(막지 않는 힌트라 버퍼가 차면 그냥 버립니다 — 다음 주기가 어차피 같은 메모를 찾습니다)
• AI 제외는 그대로입니다. 제외된 생각은 별도 묶음으로 넘겨 로컬 알고리즘으로 계산합니다. 한 묶음에 섞으면 ensureEmbeddings 가 묶음 전체를 로컬로 떨어뜨려서, 제외되지 않은 남의 생각까지 설정한 모델을 못 쓰게 됩니다
• 벡터가 최신이어야 하는 기능(연결 추천 · 아침 브리핑 · 공간 추천)은 스스로 sweep을 한 번 돌리고 시작합니다. 정상 상태에선 아무것도 못 찾는 질의 한 번입니다

임베딩 타임아웃 (v0.72.0)

embedding_timeout_seconds 가 생겼고 기본 10초입니다. 예전에는 timeout_seconds 하나를 채팅과 공유해서, 긴 추론 모델에 넉넉히 준 시간이 그대로 검색이 기다리는 시간이 됐습니다. 안 정하면 채팅 값으로 떨어지지 않습니다 — 그러면 분리한 의미가 없습니다.

협업 로그가 사본을 두지 않습니다 (v0.68.0)

AppendSpaceEvent 는 payload 하나를 만들어 세 곳에 씁니다. 셋의 요구가 다릅니다.

셋 중 본문이 필요 없는 유일한 곳이, 유일하게 정리도 안 되는 곳이었습니다. 결과적으로 모든 메모의 모든 판본이 무기한 쌓였고 작성자가 지운 메모의 본문까지 남았습니다(soft delete라 space_events 행은 그대로입니다). 시험 DB 실측으로 662행 중 629행이 본문을 담고 있었습니다.

이 표를 읽는 소비자는 SSE로 연결된 캔버스 하나뿐이고, 클라이언트 코드는 actorId 만 보고 다시 불러옵니다 — payload는 한 번도 읽힌 적이 없습니다.

• 지금은 space_events.payload 가 항상 {} 입니다. 무엇이 바뀌었는지는 event_type 과 resource_id 로 충분합니다
• 마이그레이션 026이 기존 행의 payload도 비웁니다. 되돌리는 down 마이그레이션은 없습니다 — 지운 내용은 복구할 수 없고, 컬럼을 되돌린다고 돌아오지도 않습니다
• 웹훅 구독자가 받는 본문은 그대로입니다. 시험이 그쪽을 함께 확인합니다 — 아니면 이 수정은 기능 제거입니다

연결에 적힌 이유 (v0.65.0)

• 자체 컬럼 note_edges.reason, 200자 CHECK. 010에서 relation 이 자유 텍스트였던 것과는 다릅니다 — 그때 문제는 한 컬럼이 의미와 출처 둘을 담았던 것이지 이유를 적으면 안 된다는 게 아니었습니다
• 길이는 글자 수로 셉니다. 바이트로 세면 한국어 허용량이 3분의 1로 조용히 줄어듭니다. SQL char_length 와 Go utf8.RuneCountInString 이 같은 것을 셉니다
• 자르지 않고 거절합니다. 400 + maxLength. 남의 문장을 반만 저장하는 것이 안 하는 것보다 나쁩니다
• 편집 권한이 필요합니다 — 공간에 주석을 다는 것도 공간을 바꾸는 일입니다
• 마크다운 내보내기의 ## Connections 줄 뒤에 — 이유 로 붙고, 가져오기가 같은 형태로 읽습니다. (origin) 은 읽고 지나갑니다 — 출처는 파일이 주장할 수 있는 것이 아니고, 이건 API가 request body에 적용하는 규칙과 같습니다

함께 막은 것: 연결 쓰기 권한 구멍

notes:read 만 가진 API 키가 연결을 지울 수 있었고, umm이 추측한 연결을 채택해서 그래프에 넣을 수도 있었습니다. POST /spaces/{id}/edges 에는 notes:write 검사가 있었지만 DELETE /edges/{id} 와 POST /edges/{id}/accept 에는 없었습니다. 세 번째 문(PUT /edges/{id}/reason)을 내면서 발견했고, 셋 다 막았습니다. 시험이 네 문을 전부 걷습니다 — 한 문만 빠뜨리는 것이 이 결함이 계속 돌아오는 모양이기 때문입니다.

분량 맞추기 (v0.64.0)

AI가 아닙니다. 이 옵션만은 모델을 호출하지 않고, 그건 못 해서가 아니라 그게 맞아서입니다.

• 무엇을 남길지는 그래프가 정합니다: 몇 개의 생각이 그 슬라이드에 닿았는지(From), 부 제목인지, 표시해 둔 맞섬인지. 전부 사람이 한 일이고, 글자는 하나도 읽지 않습니다
• 같은 공간 + 같은 분량 = 같은 덱. 미리보기가 읽을 만한 이유가 이것입니다. 모델이 정하면 만들 때마다 달라지고, 그러면 미리 본 것과 만들어진 것이 다릅니다
• AI 모델이 없어도 됩니다. 대부분의 설치가 그렇습니다
• 설명할 수 있습니다. “연결이 하나도 없어서 빠졌습니다”는 사람이 반박하고 고칠 수 있는 문장입니다. “모델이 이걸 골랐습니다”는 아닙니다
• 맞섬 슬라이드는 마지막까지 남습니다. 같은 메모를 요약해서는 절대 나오지 않는 슬라이드이기 때문입니다
• 순서는 건드리지 않습니다. 무엇이 들어갈지를 정하는 것이지 어떤 순서일지를 정하는 게 아닙니다
• 부 제목도 셉니다. 20장을 고르고 24장을 받으면 고른 분량이 아니므로, 부로 나눈 뒤 한 번 더 맞춥니다. 그래서 부로 나누면 내용 슬라이드가 그만큼 줄어듭니다 — 분량을 정한다는 게 그런 뜻입니다
• 10장 미만처럼 12장에 못 미치는 분량을 고르면 부 나누기는 아예 동작하지 않습니다. 짧은 발표는 나눌 필요가 없고, 분량이 먼저 적용되기 때문입니다
• 들어가지 못한 생각 수는 trimmedCount 로 저장됩니다. excludedCount 와 따로 두는 이유는 뜻이 달라서입니다 — 제외는 작성자가 분석에서 빼 둔 것이고, 이건 분량을 늘리면 그대로 돌아옵니다

모델이 주제와 견줘 무게를 다는 일은 그래프가 못 하는 일이고, 이건 그걸 하지 않습니다. 다만 손실은 생각보다 작습니다: 사람은 이미 어떤 생각으로 만들지 직접 고를 수 있고, 그게 모델의 추측보다 나은 답입니다.

큰 공간이 실패하는 경로

덱 만들기는 두 번의 호출입니다. Ptium이 덱을 열고, 그다음 umm이 소스를 컴파일해 넣습니다. 두 번째가 실패하면 덱은 이미 만들어져 있고 비어 있습니다. 예전에는 버튼을 다시 누르면 덱이 하나 더 생겼습니다.

v0.61.0부터는 실패 응답이 그 덱을 지목하고(ptiumId, deckLeftBehind), 화면이 “만들어진 발표 자료에 이어서 넣기” 를 제안합니다. Ptium의 소스 엔드포인트는 덮어쓰기라 두 번 넣어도 한 번 넣은 것과 같습니다.

큰 공간에서 가장 흔한 실패는 timed-out 입니다. 기본 timeout_seconds 는 30입니다. 슬라이드가 80장을 넘으면 화면이 보내기 전에 경고합니다 — 그 숫자는 umm이 자기 쪽에서 이미 알고 있기 때문입니다. 측정된 Ptium 한계가 아니라 “발표 하나로 읽을 만한가”에서 잡은 값입니다.

기술 정보는 관리자에게만 갑니다

바탕이 된 오류 메시지는 내부 호스트 주소, Go 타입 이름, SQL 제약 이름을 담고 있습니다. 슬라이드를 만들려던 사람에게는 쓸 데가 없고 보여 줄 이유도 없으므로, admin 역할일 때만 응답의 technical 에 실립니다. 화면에서는 “기술 정보 (관리자에게만 보입니다)” 아래에 접혀 나옵니다.

앞단 프록시가 Ptium 대신 HTML 오류 페이지로 답하는 경우, 그 페이지는 Ptium의 설명이 아니므로 “Ptium이 보낸 설명”에 싣지 않습니다. 프록시는 Ptium이 아니고, 그 페이지는 상태 코드 이상을 말해 주지 않습니다.

지난 실패를 나중에 보기

발표 목록의 실패 배지에 마우스를 올리면 같은 분류가 뜹니다. 바탕이 된 오류는 presentation_links.error 에, 분류는 failure_kind 에 남습니다. v0.60.0 이전에 기록된 행은 failure_kind 가 비어 있고, 그때는 저장된 원본 오류를 그대로 보여 줍니다.

부록 9. 서명 웹훅 운영

사용자는 개인 설정에서 허용된 webhooks:write scope로 subscription을 관리합니다. 대상은 공개 HTTPS 443만 허용합니다. 도메인 변경과 PostgreSQL delivery outbox는 원자적으로 커밋되고, 재시작 시 대기 또는 lease가 만료된 항목을 이어서 처리합니다. 전달 worker는 구독·소유 사용자·이벤트 공간·현재 membership과 정확한 delivery claim을 실제 HTTP 응답까지 잠급니다. 권한 회수·사용자 비활성화·구독 중지가 먼저 확정되면 payload를 보내지 않고, 전송이 먼저 시작되면 변경 transaction은 delivery terminal 상태와 payload 삭제가 확정될 때까지 기다립니다. 수신 시스템은 timestamp와 raw body의 HMAC-SHA256, 허용 시간 창을 검증하고 at-least-once 요청의 delivery UUID를 멱등 처리해야 합니다. 일시 실패는 세 번 재시도하고 연속 10회 실패 subscription은 자동 중지됩니다. 외부 오류는 잘못된 UTF-8을 제거하고 500 byte의 완전한 rune 경계 안에서 기록하므로 다국어 오류도 실패 횟수와 자동 중지를 막지 않습니다. terminal payload는 즉시 제거되고 metadata도 30일 후 정리되므로 운영 지표와 개인 설정의 마지막 오류를 함께 확인하세요.

어느 웹훅이 실패하고 있는지 (/admin/webhooks)

운영 현황에는 “최근 웹훅 실패” 숫자 하나만 있었습니다. 어느 웹훅인지, 누구 것인지, 수신 쪽이 뭐라고 답했는지는 모두 기록돼 있는데 아무것도 보이지 않았으니, 그 숫자는 뭔가 잘못됐다는 사실만 알려 주고 어디를 봐야 할지는 알려 주지 않았습니다.

관리자 → 웹훅 상태는 설치된 모든 웹훅을 나쁜 것부터 보여 줍니다. 연속 실패 횟수, 최근 24시간 실패, 마지막 전송 시각, 수신 쪽이 마지막으로 돌려준 오류, 소유자와 그 계정의 활성 여부, 아직 큐에 남아 있는 전달 수가 한 줄에 있습니다. 실패한 것만 을 켜면 실패가 기록된 것만 남습니다.

보내는 곳은 scheme과 host까지만 표시합니다. Slack이나 Discord의 incoming hook처럼 주소의 경로 자체가 자격 증명인 경우가 흔하기 때문에, 전달이 어디로 가는지는 보여 주되 그 주소로 직접 보낼 수 있게 하지는 않습니다.

멈추기는 active만 내립니다. 주소, 서명 키, 이벤트 목록은 그대로 남아 소유자가 개인 설정에서 다시 켤 수 있고, 이 조치는 webhook.pause로 감사 로그에 남습니다. 이미 멈춘 웹훅을 다시 멈춰도 오류가 아닙니다.