유지보수
이 페이지는 영어 원문을 기계 번역한 것이며, 영어 원문이 기준입니다. Machine-translated from the English page, which is authoritative.
여기에 나오는 모든 명령은 loom 하위 명령이며, 배포 환경의 환경 변수가 설정된 컨테이너 안에서 실행합니다(docker exec loom-server loom …, 분리 배포에서는 loom-workers). 모든 플래그는 CLI 레퍼런스에서 확인할 수 있습니다. 코드 인덱스에는 별도의 운영 문서가 있습니다: 코드 인덱스 운영.
쓰기를 실행하기 전에
아래 명령 대부분은 **기본적으로 드라이 런(dry run)**으로 동작합니다. 출력을 확인하고 --org와 --namespace로 범위를 지정한 다음, 쓰기 플래그(--apply, 삭제의 경우 --erase)를 전달하세요. 각 표에 해당 플래그와 예외가 명시되어 있습니다. 변경(ALTER … UPDATE)을 제출하는 명령은 ClickHouse가 해당 변경을 적용하기 전에 반환됩니다. system.mutations를 확인하세요.
다시 임베딩 및 다시 추출
loom reembed는embedding_model이 구성된 임베더와 다른 메모리, 엔터티, 대화 벡터를 다시 임베딩합니다. Loom 은 스스로 다시 임베딩하지 않으므로LOOM_EMBEDDING_MODEL(및LOOM_EMBEDDING_DIM)을 변경한 뒤에 실행하세요.--org/--namespace로 범위를 지정하고,--dry-run은 행 수만 셉니다.--delete-old는 이후에 이전 모델의 행을 제거합니다.--key-only는 각 라이브 행의 키 축 벡터만 다시 만듭니다. 단, 가져오기 키(import:와 다이제스트)는 키 축 벡터가 없으므로 예외입니다. 벡터가 없는 행은 건너뛰고, 이전 빌드가 임베딩해 둔 행은 벡터를 비웁니다.--in-database <named collection>은 Python 루프 대신 ClickHouse 안에서aiEmbed(ClickHouse 26.7 이상)로 테이블마다INSERT … SELECT한 번씩으로 임베딩을 실행합니다. 고객 또는 아이덴티티 헤더가 설정되어 있거나 추론 게이트웨이가 필수인 경우에는 거부됩니다. ClickHouse 자체의 호출은 고객이나 아이덴티티를 지정하지 않으며 게이트웨이의 호스트 검사도 건너뛰기 때문입니다. Python 경로는 정렬 키 순서로--batch-size행씩 읽고 페이지마다resume:토큰을 출력하며,--resume <token>으로 중단된 실행을 그 지점부터 이어갑니다. Python 경로는 텍스트가 높음(high)으로 판정되는 대화 턴을 임베더에 보내지 않습니다. 그 행은 검색이 읽지 않는 이전 모델에 남아 있다가--delete-old가 제거합니다. 메모리 행의 벡터는 민감도 레이블을 따릅니다.--in-database는 텍스트를 검사할 수 없어 그런 턴도 다시 임베딩하지만, 검색은 여전히 그 턴을 제외합니다 (민감도).- Python 경로는 각 페이지를 삽입하기 전에 해당 페이지의 행을 키로 다시 읽습니다. 페이지를 읽은 이후 삭제되었거나, 톰스톤 처리되었거나, 텍스트나 에이전트 또는 사용자가 바뀐 행은 건너뜁니다. 그 외의 모든 행은 두 번째 읽기에서 확인된 다른 컬럼 값 그대로 기록됩니다.
- 건너뛴 행이 다른 텍스트나 아이덴티티로 여전히 저장된 이전 모델 행이면,
--delete-old는 해당 org 의 이전 모델 행을 다음 실행을 위해 남겨 둡니다. 다음 실행은 그 org 의 이전 모델 행을 모두 다시 임베딩합니다(--org로 범위를 지정하세요).resume:토큰에는 지금까지 남겨 둔 org 가 담겨 있으며, 실행은 삭제하기 전에 그 org 를 출력합니다. - 그 읽기와 삽입 사이에 발생한 삭제, 편집(redaction) 또는 삭제 요청(erasure)이나 아직 행에 반영되지 않은 뮤테이션은 행을 새 벡터와 함께 라이브 상태로 남길 수 있습니다. 이런 편집은 실행이 끝난 뒤 다시 수행하고, 이런 대화 턴이나 스레드는 다시 삭제하세요. 고아 벡터 정리 작업은 삭제된 메모리의 남은 벡터를 톰스톤 처리하며, 삭제 요청의 검증 단계는 해당 행을 찾아 다시 시도합니다.
--in-database는 문이 시작될 때 각 테이블을 한 번만 읽으므로, 편집이나 삭제 요청이 없을 때 실행하세요.
- 다른 차원의 모델. ClickHouse 26.8 이상에서 새로 설치하면
enable_quantized_codec을 켤 수 있는 곳에서 벡터 컬럼이 코딩(Quantized)되며(ClickHouse), 코딩된 컬럼은 생성 시의 차원을 가진 벡터만 받습니다. 다른 차원(8의 배수)의 모델로 바꾸려면 Settings → Models & keys 에서 변경하세요. 그러면 새 차원으로 벡터 테이블을 다시 만듭니다.loom reembed는 테이블이 받지 않는 차원을 거부하며,LOOM_EMBEDDING_DIM만 수정하면 모든 벡터 쓰기가 503CODED_WIDTH_MISMATCH로 응답하고/v1/health는coded_width_mismatch를 보고합니다. loom rechunk --org ORG --namespace NS는 저장된 콘텐츠로 모든 라이브 문서에knowledge.upsert를 다시 실행하여 문서가 현재의 청킹, 청크 컨텍스트, 벡터를 반영하게 합니다(문서 하나만 처리하려면--source-uri).--apply를 지정하기 전까지는 드라이 런입니다.loom lexical-stats-rebuild --org ORG --namespace NS는 라이브 행에서 BM25 문서 빈도를 다시 계산합니다. 용어 빈도 뷰는 삽입만 보기 때문에, 대체(supersession), 톰스톤, 대량 삭제가 일어나면 이 명령을 실행하기 전까지 오래된 어휘가 남습니다(--no-memory/--no-knowledge로 한쪽을 건너뜁니다). 즉시 기록합니다.loom reextract --org ORG --namespace SRC --into DST는 한 네임스페이스에 저장된set_from_messages대화록을 실행 중인 서버의 현재 추출기로 다시 처리하여 다른 네임스페이스에 넣습니다(--token은DST의 writer 토큰이며, 없으면$LOOM_API_KEY, 그다음~/.loom/token을 사용합니다). 원본은 읽기만 하므로 읽기 쪽을 전환하기 전에 두 네임스페이스를 비교할 수 있습니다.--dry-run은 세션 목록을 보여 주고,--limit-sessions N은 일부 샘플만 다시 처리합니다.loom recalibrate는 임베더를 다시 탐색하고 적응형 유사도 임계값을 즉시 다시 계산합니다. 그렇지 않으면recalibration워커가 매주 수행합니다.
새 벡터 공간은 모든 유사도 점수를 바꾸기 때문에 다시 임베딩은 수동으로 합니다. 직접 실행하면 전환, 비용, 검색 품질의 기준선 재설정이 운영자의 한 단계로 묶입니다.
백필과 복구
| 명령 | 동작 | 쓰기 플래그 |
|---|---|---|
loom integrity-repair |
무결성 게이지와 그 근거가 되는 행을 출력합니다. 검색에서 보이도록 dim0_with_vector 행을 다시 내보냅니다(드리프트 행과 valid_to 행은 목록으로만 표시합니다) |
--apply |
loom sensitivity-sweep |
민감도 탐지기가 레이블을 붙일 라이브 상태의 레이블 없는 행의 수를 셉니다. 쓰기를 실행하면 레이블을 붙이고, high 행의 임베딩 행은 삭제 표시(tombstone)합니다 |
--apply |
loom reconcile-status |
상태가 loom.memory와 달라진 memory_embeddings 행을 다시 내보냅니다 |
--apply |
loom demote-activity-narration |
지속되는 결과 없이 도구 활동만 서술하는 추출된 사실을 찾아 memory.apply를 통해 강등하거나 레이블을 붙입니다. 삭제는 하지 않습니다 |
--apply |
loom namespaces-adopt |
라이브 메모리는 있지만 레지스트리 행이 없는 네임스페이스에 소유자 행을 부여합니다 | --apply |
loom namespaces-gc |
접두사로 유휴 상태의 벤치마크 네임스페이스를 찾거나(--worker-pass를 쓰면 namespace_gc 패스를 한 번 실행), 해당 네임스페이스의 삭제를 제출합니다 |
--erase |
loom audit-namespace |
네임스페이스 사용 방식(정확한 키 읽기 대비 검색, 크기가 과도하거나 이중 인코딩된 값, 버전 변동)을 보고합니다. 읽기 전용이며, 심각한 문제가 있으면 종료 코드 1을 반환합니다 | 읽기 전용 |
이 복구 명령들이 다루는 무결성 게이지는 모니터링에 나와 있습니다. 행의 형태가 잘못된 네임스페이스(문서가 메모리로 저장되었거나 리스가 사실로 저장된 경우)를 정리하는 방법은 네임스페이스 최적화에서 단계별로 안내합니다.
메모리 수집 드롭
수집 파이프라인이 데이터를 버리거나, 잘라내거나, 처리를 포기하는 모든 지점에서 드롭이 기록됩니다(server/memory/app/drops.py, record_drop). 드롭은 프로세스 내에 버퍼링되고, loom.memory_drops(30일 보관)로 플러시되며, 카운터 loom.memory.drops{stage, reason}에도 반영됩니다. 드롭 기록은 예외를 발생시키지 않으며, 드롭을 유발한 쓰기를 막지도 않습니다.
docker exec loom-server loom drops --namespace NS [--org ORG] [--hours 24]
이 명령은 해당 기간의 stage와 reason별 건수를 각 조합이 마지막으로 관측된 시각과 함께 출력합니다. SELECT * FROM loom.memory_drops WHERE namespace = '…' ORDER BY ts DESC는 개별 항목을 보여줍니다(item에는 키 또는 필드 이름이 들어가며, 메트릭 레이블로는 사용되지 않습니다).
stage에는 extract.parse, extract.judge, extract.truncate, write, entity.extract, consolidate.merge, records.field, chunk.split, conflict.deferred가 있습니다.
완전히 실패한 추출은 드롭이 아닙니다. set_from_messages는 502 EXTRACTION_FAILED로 응답하며, 부분 실패는 응답의 pipeline_errors에 담겨 반환됩니다.
엔티티 그래프 유지 관리
loom.entity_edges를 기록하는 writer는 어휘적 불용어(대명사, 감탄사, 경동사, 축약형 조각, 두 글자 토큰)를 그래프에서 걸러냅니다.
메모리보다 그래프가 더 오래 남아 있는 네임스페이스는 loom erasure-re-verify --org ORG --orphan-graph로 조회하고 --erase로 삭제합니다.
삭제
| 호출 | 효과 | 사용 목적 |
|---|---|---|
memory.clear (ADMIN) |
네임스페이스 내 하나의 user_id 또는 agent의 메모리에 삭제 표시(tombstone)를 합니다. confirm_subject에 범위 값을 동일하게 입력해야 합니다 |
정리, 테스트 초기화; memory.restore로 되돌릴 수 있음 |
erasure.request (scope_type: user_id, namespace 또는 namespace_list) |
대상의 콘텐츠를 담을 수 있는 모든 Loom 테이블과 설정된 외부 백엔드(Langfuse, ClickStack)에 걸쳐 실행되는, 재개 가능한 saga | 사용자 데이터 삭제(감사 추적은 유지됨); 네임스페이스 폐기 |
saga는 각 단계를 loom.erasure_requests(ReplacingMergeTree, 행은 89일 동안 읽히고 90일에 삭제됨)에 체크포인트로 기록합니다. 단계를 마친 뒤에는 읽기 경로가 접근하는 모든 테이블에 대해 잔여 데이터 조사(residue census)를 실행합니다. 범위 안에 남은 행이 하나라도 있으면 saga는 실패하며, 마지막 행에는 residue_count, residue, verified_at, census가 담깁니다. 삭제를 확인하지 못하는 백엔드가 있으면 saga는 실패 처리(fail closed)됩니다. erasure_recovery 워커는 max_attempts까지 멱등적으로 재시도하고, 그 후에는 failed 상태로 남겨 둡니다. purge: true는 삭제 표시 대신 완전히 삭제합니다(임시 네임스페이스용이며, 복원 기간이 없습니다). external: false는 외부 백엔드를 건너뛰며 namespace_list에서만 허용됩니다. 삭제가 보장하는 것과 보장하지 않는 것은 보존 및 삭제에 설명되어 있습니다.
SELECT id, scope_type, scope_value, status, current_step, attempts, failure_reason, residue_count
FROM loom.erasure_requests FINAL
WHERE status != 'completed' ORDER BY requested_at DESC LIMIT 20;
loom erasure-re-verify --org ORG는 실패한 각 saga의 마지막 실패 사유와 해당 범위에 대한 새 잔여 데이터 조사 결과를 읽기 전용으로 출력합니다(saga 하나만 보려면 --id). 사용자 saga는 요청 시 사용한 purge 값으로 조사합니다. --resume은 실패한 saga를 같은 방식으로 체크포인트부터 다시 실행하며, 복구 워커의 시도 횟수 한도를 넘어서도 실행합니다. 마지막 조사에서 행이 발견된 테이블을 담당하는 단계는 체크포인트에 완료로 기록되어 있어도 다시 실행됩니다. --skip-external(--resume과 함께 사용하며, 실패한 namespace_list saga에만 적용되고 --completed-since와 함께 쓰면 거부됨)은 외부 백엔드가 계속 실패할 때 Loom 테이블만 먼저 마무리합니다. --completed-since <ISO timestamp>는 실패한 saga 대신, 잔여 데이터 조사가 해당 시각 이후에 실행된 완료된 saga를 대상으로 합니다(타임스탬프에 오프셋이 없으면 UTC). 롤아웃 후 이전 빌드가 실행한 삭제를 확인할 때 사용합니다. 이 경우 saga 범위 안의 고아 행 링크(메모리에 살아 있는 행이 없고 saga의 조사 이후 기록된 행도 없는 entity_triple_rows와 entity_edge_rows의 행)만 집계하고, --resume을 함께 쓰면 그것만 삭제합니다. saga 단계는 다시 실행하지 않으므로, 삭제 이후에 기록된 데이터는 memory.delete가 삭제 표시를 한 뒤에도 남습니다. saga를 복구할 수 없으면 같은 erasure.request를 다시 실행하십시오. 이 작업은 멱등적입니다.
ClickStack 삭제 인덱스
ClickStack 단계는 속성 값이 일치하는 OTel 행을 삭제합니다. ClickStack 스키마는 모든 OTel 테이블의 속성 맵에 bloom filter 인덱스를 두며, schemas/otel/clickstack_otel_tables.sql은 이 인덱스와 함께 테이블을 생성합니다. 다른 설치 도구가 mapValues(Attributes) 없이 만든 otel_metrics_* 테이블은 삭제할 때마다 전체를 스캔하게 됩니다. loom doctor와 /v1/health는 누락된 인덱스를 otel_erasure_index로 보고합니다. CREATE TABLE IF NOT EXISTS는 기존 테이블에 인덱스를 추가하지 않으므로, 테이블마다 한 번씩 직접 추가해야 합니다.
ALTER TABLE default.otel_metrics_histogram
ADD INDEX IF NOT EXISTS idx_attr_value mapValues(Attributes) TYPE bloom_filter(0.01) GRANULARITY 1;
ALTER TABLE default.otel_metrics_histogram MATERIALIZE INDEX idx_attr_value;
-- repeat for otel_metrics_sum and otel_metrics_gauge (and the other metrics tables if populated)
ClickHouse Cloud에서는 ADD INDEX 직후에 실행한 MATERIALIZE INDEX가 아무것도 빌드하지 않을 수 있습니다. 해당 테이블의 system.data_skipping_indices에서 data_compressed_bytes를 확인하고, 값이 0이면 MATERIALIZE를 다시 실행하십시오.
보존
Loom은 작성자가 삭제하기 전까지 모든 행을 보관합니다. 기본적으로 기간에 따라 삭제되는 데이터는 없으며, 보존 게이지(loom.retention.*)는 삭제 후보의 수만 셉니다.
- 테이블별.
audit_log,agent_events,memory,memory_embeddings,conversations,chunks,documents에는LOOM_RETENTION_<TABLE>_DAYS=N을 사용합니다. - 네임스페이스별. 네임스페이스 등록(
namespace.register)의retention_days를 사용합니다. 관리되는 테이블의 TTL은 이 값을 설정한 모든 네임스페이스에 대한 하나의multiIf가 됩니다. - 워커의 리더가 부팅 시
MODIFY TTL을 적용합니다. 그 이후에는retention_reconcile워커만 테이블 TTL을 기록하므로, 정책 변경은LOOM_RETENTION_RECONCILE_INTERVAL_SECONDS안에 테이블에 반영되며, 등록이 한꺼번에 몰려도 테이블을 등록마다 한 번씩 다시 쓰지 않습니다.
핫/웜 티어링은 ClickHouse 스토리지 정책을 사용합니다. LOOM_TIERING_<TABLE>_WARM_DAYS=W와 함께, storage_policies에 있는 볼륨의 이름인 LOOM_TIERING_WARM_VOLUME_NAME을 설정합니다.
일부 운영용 테이블은 메모리가 아니라 진단용이므로 고정된 자체 TTL을 가집니다. loom.memory_drops(30일), loom.worker_status(30일), loom.erasure_requests(90일, 읽기는 89일에서 멈춥니다)가 그렇습니다. 모든 테이블의 TTL은 스키마 레퍼런스에서 확인할 수 있습니다.
Compaction과 OPTIMIZE
loom.memory와 loom.shared는 ReplacingMergeTree(version) 테이블입니다. 업데이트, 툼스톤, 복원은 모두 새 버전을 기록하고, 백그라운드 머지가 이 버전들을 하나로 합칩니다. 읽기 쿼리는 FINAL을 사용하므로 합쳐지지 않은 버전은 정확성이 아니라 읽기 시간에 비용을 줍니다. loom.memory에서 count() / uniqExact(memory_key) 비율이 크면 합쳐지지 않은 버전이 많다는 뜻입니다. 대량 삭제 후에는 머지가 따라잡도록 기다리거나, 부하가 낮은 시간에 OPTIMIZE TABLE loom.memory FINAL을 실행하세요.
코드 인덱스의 벡터 테이블에는 머지하기 전에 먼저 측정하는 명령이 있습니다.
docker exec loom-workers loom code compact # measure copies per key
docker exec loom-workers loom code compact --table all --apply # OPTIMIZE … FINAL where the ratio is reached
이 명령은 키당 물리적 복사본 수가 --min-ratio(기본값 LOOM_CODE_COMPACT_MIN_RATIO, 1.5)에 도달하면 코드 벡터 테이블(기본값 code_chunks_prefix, 그 외 code_chunks, all, 또는 LOOM_CODE_VECTOR_TABLES에 있는 테이블)에 OPTIMIZE … FINAL을 실행하고, 머지가 끝나기를 기다립니다(--timeout-s). code_chunks는 코드 비중이 큰 배포에서 가장 큰 테이블이므로, 사전에 공지한 시간대에 compaction하세요. 대량 처리 작업은 LOOM_CODE_COMPACT_AFTER_BULK_ROWS 행 이후 스스로 compaction합니다.
테이블의 정렬 키, 파티션 키 또는 벡터 코덱을 변경하는 일은 ALTER가 아니라 재구축으로 처리합니다. scripts/ops/table_rebuild.py와 scripts/ops/vector_codec_rebuild.py는 트윈 테이블로 복사하고, 검사한 뒤 EXCHANGE TABLES로 교체하며, 이전 테이블은 --rollback을 위해 보관합니다. 두 스크립트 모두 계획을 출력하며 --yes 없이는 아무것도 변경하지 않습니다. 정렬 키와 파티션 키 절차는 마이그레이션에, 벡터 코덱 절차는 권장 설정에 있습니다.
vector_codec_rebuild.py는 모든 writer와 삭제 작업을 중지하고 처리 중인 쓰기를 모두 비운 유지보수 시간대가 필요합니다. 이 스크립트는 라이브 테이블을 복구하지 않습니다. 복사하기 전에, 원본 테이블에서 mutation이 아직 실행 중이거나 최근 1분 이내에 생성되었으면 실행을 거부합니다. 이 1분은 레플리카 간 시계 차이를 감안한 값이며, 교체 전 게이트도 이를 포함해 계산합니다. 마지막 mutation이 끝나고 1분 뒤에 다시 실행하세요. --reuse를 사용하면 재사용하는 트윈이 생성된 이후의 모든 mutation을 완료된 것까지 포함해 셉니다. 그런 mutation이 있으면 트윈이 오래된 것이 되므로, --restart --yes로 다시 실행해 처음부터 복사해야 합니다. 또한 --reuse는 이름이 지정된 컬럼, granularity, 정렬 키가 이번 실행이 만들 트윈과 다른 트윈도 거부합니다(다른 --method, --index-granularity, --chain, 또는 다른 도구가 만든 트윈). 게이트는 저장된 벡터와 코드를 읽으므로 이 차이를 알아차리지 못하기 때문입니다. 빈 테이블도 재구축됩니다. 이때 폭은 아래 폭 항목이 정하는 값(코드화된 컬럼 자체의 폭, 아니면 LOOM_EMBEDDING_DIM)을 따르며, recall 게이트는 빈 테이블에서 조사할 행이 없습니다. 이 스크립트의 ClickHouse 사용자에게는 테이블에 대한 SYSTEM FLUSH ASYNC INSERT QUEUE와 SYSTEM SYNC REPLICA 권한이 필요하고, ReplicatedMergeTree에서는 system.zookeeper와 system.replication_queue에 대한 SELECT(loom ch-setup이 부여하지 않음), 그리고 트윈 loom.<table>_rebuild에 대한 SYSTEM SYNC REPLICA(게이트가 읽기 전에 동기화함)와, 교체가 만드는 롤백 복사본 loom.<table>_pre_rebuild에 대한 같은 권한(교체 후 검사와 --drop-pre-rebuild가 동기화함)도 필요합니다. 사전 점검은 앞의 두 권한을 한 번 실행해 보고, 하나라도 실패하면 오류를 명시하며 거부합니다(종료 코드 3). 나머지는 해당 테이블이 존재해야만 실행할 수 있으며, 트윈 동기화가 거부되면 게이트가 실패합니다(종료 코드 5).
--dry-run도 앞의 두 가지를 실행하므로, 큐에 대기 중인 행을 테이블에 반영하고 뒤처진 레플리카에서는 동기화를 기다리지만, 그 외에는 아무것도 쓰지 않습니다. 게이트가 실패하면(종료 코드 5) 쓰기와 삭제를 중지하고 --restart로 다시 실행하세요. 단, 테이블에 행은 있지만 조사할 실제 벡터가 없는 경우는 예외입니다. 다시 실행해도 같은 방식으로 실패하므로, 실행 결과의 next가 안내하는 대로 트윈을 삭제하고 테이블에 임베딩이 채워질 때까지 건너뛰세요. 폭 거부(종료 코드 3)는 아래의 재임베딩이 필요합니다.
재구축이 끝나거나 중단되고 모든 <table>_rebuild 트윈과 <table>_pre_rebuild 롤백 복사본이 제거될 때까지 writer와 삭제 작업을 중지된 상태로 유지하세요. 교체에 성공하면 로그와 요약 줄의 next에 이 안내가 다음 단계로 출력됩니다. 명령을 알려주는 각 다음 단계에는 이번 실행의 --method, --chain, --index-granularity, --gate-fetch-multiplier, --probes, --require-patch-free, --cluster, --statement-timeout-s, 그리고 기본값이 아닐 때 --abort-file(트윈의 기록이 그 옆에 있음)이 포함되므로, 출력된 그대로 실행하면 됩니다. 검증 또는 롤백 후 롤백 복사본을 제거하려면 --drop-pre-rebuild --yes를 사용하세요. 버려진 트윈은 해당 테이블 줄의 --dry-run 결과가 not swapped로 시작하는 다음 단계를 출력할 때에만(검사용으로 남긴 트윈이거나, 교체되지 않고 남은 잔여물일 때) DROP TABLE loom.<table>_rebuild SYNC로 제거하세요. 다음 단계가 RENAME TABLE loom.<table>_rebuild TO loom.<table>_pre_rebuild를 안내하거나 두 테이블을 비교하라고 하면, 먼저 그렇게 하고 아무것도 삭제하지 마세요. 이름 변경 단계가 나온다는 것은 교환은 실행되었지만 이름 변경은 실행되지 않았다는 뜻이며, 이때 <table>_rebuild가 이전 테이블입니다. 이름 변경을 실행하기 전까지는 해당 테이블 줄의 모든 실행(--yes, --reuse, --restart를 붙인 같은 줄 포함)과 --drop-pre-rebuild가 종료 코드 3으로 거부됩니다. 도구는 이를 실행 플래그가 아니라 두 테이블의 모든 벡터 컬럼에서 읽어 판단하므로, 다른 --method, --chain, --index-granularity, --columns로 다시 실행해도 거부됩니다. 코드화된 벡터 컬럼이 있는 라이브 테이블 아래에서, 잔여물로 확인되지 않은 트윈은 이전 테이블일 수 있기 때문입니다. 라이브 테이블에서 코드화된 각 컬럼이 트윈에서는 일반 컬럼이면, 도구가 이름 변경 명령을 알려줍니다. 트윈에서도 하나가 코드화되어 있으면(--require-patch-free 실행이거나 코드화된 테이블의 재구축), 코덱만으로는 교환이 실행되었는지 알 수 없습니다. 이 경우 도구는 거부하고, 이름 변경도 삭제도 하지 않으며, 둘 중 하나를 수동으로 삭제하기 전에 두 테이블의 행을 비교하라고 안내합니다. 정렬 키나 파티션 키가 라이브 테이블과 다른 트윈은, scripts/ops/table_rebuild.py가 이름 변경 없이 교환해 내보낸 이전 테이블일 수 있습니다. 이 도구가 트윈과 같은 이름을 공유하기 때문입니다. 이때 모든 줄이 거부하고, 아무것도 삭제하지 않으며, 보고서가 이름 변경을 알려주는 python -P -m scripts.ops.table_rebuild --table <table> --dry-run을 안내합니다. 교환된 적 없는 트윈은 재실행이 어떤 레이아웃을 지정하든 잔여물입니다. --restart --yes로 다시 복사하거나 삭제하세요. 도구는 트윈이 생성될 때 $LOOM_REBUILD_DIR/<table>_rebuild.uuid(abort 파일이 있는 디렉터리)에 기록된 UUID가 트윈과 라이브 테이블의 UUID와 같으면 그 트윈이 교환된 적 없다고 판단하며, 이는 어떤 데이터베이스 엔진에서도 동작합니다. 교환이 한 번이라도 일어나면 라이브 테이블 이름에 다른 UUID가 붙으며, 다른 디렉터리에서 실행한 --reuse 교체도 마찬가지이고 이 경우 기록이 남겨집니다. 도구는 자체 교환 직전에 이 기록을 제거하며, 제거하지 못하면 교체를 거부합니다. 일치하는 기록이 없으면, system.tables.metadata_modification_time이 라이브 테이블보다 늦은 트윈을 교환된 적 없는 것으로 판단합니다. 이는 EXCHANGE TABLES가 각 테이블의 고유한 시간을 유지하는 Atomic 및 Replicated 데이터베이스에서 성립하는데, 라이브 테이블의 메타데이터 시간이 트윈보다 늦으면 교체가 거부되기(종료 코드 3, 트윈 유지) 때문입니다. 게이트가 도는 동안 라이브 테이블에 실행한 ADD INDEX나 MODIFY SETTING은 mutation을 만들지 않지만, 교체가 중간에 멈추면 이전 테이블이 더 새로운 쪽이 될 수 있습니다. 이런 ALTER 뒤에는 --restart로 다시 실행하세요. 시간이 같은 경우(이 컬럼은 1초 정밀도)와 그 외 데이터베이스 엔진에서는 아무것도 알 수 없으므로, 도구는 트윈을 이전 테이블일 수 있다고 간주합니다. 따라서 매번 같은 LOOM_REBUILD_DIR에서 도구를 실행하세요.
--drop-pre-rebuild는 먼저 사후 조건과 같은 드레인을 거친 뒤 두 테이블을 다시 비교하며, 두 테이블이 모두 대상 레이아웃인 경우(이미 그 레이아웃인 테이블의 --require-patch-free 재구축)에도 같습니다. 교체 후 검사가 찾아내는 항목에 해당하는 차이가 하나라도 있으면 거부하고(종료 코드 3) 복사본을 유지합니다. 두 테이블이 모두 대상 레이아웃이면 --rollback과 --drop-pre-rebuild는 메타데이터 시간이 더 늦은 테이블을 새 테이블로 간주하는데, 이는 Atomic 및 Replicated 데이터베이스에서만 가능합니다. 시간이 같거나 다른 엔진이면 둘 다 거부하고(종료 코드 3) 수동 비교를 위해 두 테이블을 모두 유지합니다.
삭제 saga는 이 복사본들을 처리하지 않습니다.
- 폭. 일반 컬럼의 대상 폭은
LOOM_EMBEDDING_DIM이므로, 배포 환경의 env로 도구를 실행하세요. 코드화된 컬럼은 자체 폭을 지정합니다.LOOM_EMBEDDING_DIM은 서빙 중인 모델의 폭과 같아야 합니다. writer는 서버가 부팅 시 모델에서 조사한 폭을 사용하며,LOOM_EMBEDDING_DIM이 낡았으면 서버 로그에embedding dim mismatch줄만 남습니다. 이름이 지정된 일반 컬럼에 다른 폭의 실제 벡터(모두 0이 아닌)가 있으면--dry-run을 포함해 도구는 거부합니다(종료 코드 3). 복사하면 그 벡터가 영벡터로 대체되고, 코드화된 컬럼은 다른 폭의 쓰기를 거부하기 때문입니다. 메시지에는 각 폭과LOOM_EMBEDDING_DIM이 표시됩니다. 모든 실제 벡터가 하나의 다른 폭이고 서버 로그가 그 폭을 모델의 폭으로 밝히면,LOOM_EMBEDDING_DIM을 그 폭으로 설정하고 다시 실행하세요. 재임베딩하지 마세요. 그렇지 않으면LOOM_EMBEDDING_DIM으로 재임베딩한 뒤 다시 실행하세요.memory_embeddings,entity_vectors,conversation_embeddings는loom reembed --delete-old를 사용하는데, 이 명령은 다른embedding_model의 행만 재임베딩하므로 같은 모델에서 폭만 바뀐 경우는 Settings → Models & keys에서 처리합니다.memory_chunks,code_chunks,code_summaries같은 다른 테이블은 각자의 writer가 재임베딩합니다. - 게이트(종료 코드 5). 일관성 게이트는 각 키의 최신 버전(버전 컬럼이 없는 테이블에서는 행 수)과 모든 컬럼의 해시를 비교합니다. 이때 원본의 재구축 대상 벡터 컬럼은 복사본이 쓰는 방식 그대로 캐스트하고 패딩합니다. 트윈에 없거나 버전이 더 오래된 키는 키 단위로 다시 복사하며, 그래도 다른 키가 남아 있으면 게이트가 실패합니다. 트윈에만 있는 키가 있어도 실패합니다. 복사 후 원본에서 행이 제거되었다는 뜻이고, 교체하면 그 행이 되살아나기 때문입니다. recall 게이트는 실제 벡터만 순위에 올립니다. 자리표시자의 코사인 거리는 NaN이기 때문입니다.
- 키와 버전이 같은 행.
FINAL에서 ReplacingMergeTree는 최신 버전에 있는 한 키의 행들 중 마지막으로 삽입된 행을 유지합니다. 그런데 복사의 병렬INSERT는 그 행들을 다른 순서로 삽입할 수 있어서, 몇 번을 복사해도 트윈이 다른 행을 유지할 수 있습니다(DateTime으로 버전을 관리하는 테이블에서 한 키를 같은 초에 두 번 쓰면 충분합니다). 어떤 키가 계속 다르면 게이트는 원본에서 이런 키의 수를 세어 메시지에 표시합니다. 시간대 안에서 원본에OPTIMIZE TABLE loom.<table> FINAL을 실행하면 키당 한 행만 남으니, 그런 다음--restart로 다시 실행하세요. - 교체 전. 도구는 원본의 async insert 큐를 flush합니다(복제 엔진에서는
SYSTEM SYNC REPLICA도 실행하는데, 이는 응답하는 레플리카만 동기화하며,LIGHTWEIGHT를 쓰는ReplicatedMergeTree에서는 머지가 아니라 fetch만 기다립니다).ReplicatedMergeTree에서는 실행하는 동안 내내 한 레플리카에 직접 연결하세요. 이후의 일관성 및 폭 읽기는 각각 같은 문장 안에서, 응답하는 레플리카가 읽는 테이블의 복제 로그 전체를 복사했는지, 그리고 큐에 머지나 mutation 외의 항목이 남아 있지 않은지도 함께 읽습니다. 항목이 하나뿐인 로그를 아직 가져오지 못한 레플리카도 빈 로그를 가진 레플리카와 같은 0의 로그 포인터를 보고하므로, 실행은system.zookeeper에서 로그의 항목을 읽어 항목이 없는 로그일 때만 0을 통과시킵니다. 이를 위해 사용자에게system.zookeeper와system.replication_queue에 대한SELECT가 필요하며, 둘 중 하나라도 읽지 못하면 뒤처진 레플리카에서 읽은 것과 똑같이 거부됩니다. 따라잡지 못한 레플리카에서 읽으면 사전 점검에서 실행이 거부되고(종료 코드 3), 교체 전 게이트가 실패하며(종료 코드 5), 교체 후 사후 조건이 실패합니다(종료 코드 7). 이후의 모든 게이트 읽기와 마지막 delta는select_sequential_consistency = 1을 사용합니다.SharedMergeTree에서는 다른 레플리카가 읽기를 처리하더라도 확인된 쓰기를 포함합니다.ReplicatedMergeTree에서는 이 설정이insert_quorum_parallel = 0인 quorum insert만 포함하며, 레플리카에 직접 연결하는 일을 대체하지 않습니다. 폭 및 일관성 검사는 삭제, 다른 폭의 쓰기, delta가 가져갈 수 없는 쓰기(트윈의 최고 버전보다 낮은 버전, 또는 버전 컬럼이 없는 테이블에서 트윈에 이미 있는 키의 행), 그리고 키와 버전은 그대로이면서 행의 컬럼(재구축 대상 벡터 포함)이 바뀌는 모든 변경(경량UPDATE나 삭제 툼스톤 등, patch part가 아직 남아 있는지와 무관)에 대해 게이트를 실패시킵니다. 그 밖의 삽입은 복사에 반영되고 교체가 진행됩니다. writer를 막는 것은 도구가 아니라 유지보수 시간대입니다. 게이트는 복사가 시작된 이후(--reuse에서는 트윈이 생성된 이후)에 실행 중이거나 생성된 원본 mutation이 있어도 실패하며, 레플리카 시계를 감안해 1분은 제외합니다. - 교체 후(종료 코드 7). 도구는 롤백 복사본을 원본으로, 새 테이블을 트윈으로 삼아 마지막 게이트 읽기와 같은 읽기 설정 및 레플리카 검사로 일관성 검사를 다시 실행하고, 복사 이후 두 테이블의 mutation을 셉니다.
ReplicatedMergeTree에서는 먼저 롤백 복사본에SYSTEM SYNC REPLICA ... LIGHTWEIGHT를 실행합니다. 롤백 복사본에는 자체 복제 큐가 있고, 교체 전에 다른 레플리카에 도달한 쓰기는 이름 변경 후 이 복사본에 속하기 때문입니다.LIGHTWEIGHT를 쓰는 이유는 교체가 복사본의 머지를 멈추게 하므로 전체 동기화는 머지 항목을 기다리게 되기 때문입니다. 머지는 어느 테이블의 행도 바꾸지 않으므로 통과합니다. 차이가 있으면 사후 조건이 실패하고 롤백 복사본이 유지됩니다. 출력되는 다음 단계는 교체 후 검사가 찾아내는 항목에 있습니다.
--statement-timeout-s(기본값 1800, 클라이언트의 읽기 타임아웃인 7200 미만)는 폭, 일관성, mutation, delta, recall 읽기(교체 후와 --drop-pre-rebuild의 읽기 포함)와 교체 전의 각 delta 및 복구에 상한을 둡니다. 테이블의 행 수, 컬럼, 카탈로그 행을 읽는 작은 읽기에는 적용되지 않으며, 복사와 롤백의 catch-up 복사(그 행을 찾는 읽기 포함)는 별도의 7000초 제한으로 실행됩니다. 교체 후에 읽기가 타임아웃되면 롤백 복사본이 유지된 채 사후 조건이 실패하고(종료 코드 7), --drop-pre-rebuild에서 타임아웃되면 복사본이 유지됩니다. 각 폭 검사(사전 점검, 교체 전, 교체 후 롤백 복사본)는 이름이 지정된 일반 컬럼의 모든 벡터를 읽고(ReplacingMergeTree에서는 FINAL 사용), 각 일관성 검사(복사 또는 복구 후, 교체 전, 교체 후)는 벡터를 포함해 두 테이블의 모든 행을 읽으므로, 타임아웃은 테이블 전체를 한 번 읽을 수 있는 값으로 설정하세요.
교체 후 검사가 찾아내는 항목
교체 후의 실행은 아래 각 항목에서 사후 조건이 실패하고(종료 코드 7) --drop-pre-rebuild는 거부하며(종료 코드 3), 두 경우 모두 롤백 복사본을 유지합니다. 요약 줄의 next에 다음 단계가 나옵니다.
| 검사에서 발견되는 항목 | 출력되는 다음 단계 |
|---|---|
교체 후 롤백 복사본에만 있는 변경: 그쪽에만 있는 키, 그쪽의 더 새로운 버전, 완료되지 않은 ALTER UPDATE, 또는 다른 폭의 벡터를 설정하는 UPDATE |
--rollback --yes: 변경을 포함해 이전 테이블을 되돌려 놓습니다 |
| 스왑 이후 라이브 테이블에만 있는 키 또는 그 테이블의 더 새로운 버전: 스왑 이후 새 테이블에 쓴 기록, 또는 마지막 확인 이후 이전 테이블에서 수행한 삭제 | 두 테이블을 모두 보존하고 차이를 직접 확인합니다 |
한 버전에서 내용이 다른 키: 병합 여부와 관계없이 어느 한쪽 테이블에서 수행한 경량 UPDATE, 또는 스왑 이전에 끝난 ALTER UPDATE |
두 테이블을 모두 보존하고 차이를 직접 확인합니다 |
스왑 이후 복사가 시작된 뒤 라이브 테이블에서 일어난 뮤테이션, 예를 들어 loom reembed --delete-old가 실행하는 경량 DELETE |
두 테이블을 모두 보존하고 차이를 직접 확인합니다 |
| 두 테이블의 컬럼 이름이 서로 다름 | 두 테이블을 모두 보존하고 차이를 직접 확인합니다 |
| 롤백 이후 새 레이아웃 복사본에만 있는 변경, 또는 생성 이후 그 복사본에서 일어난 뮤테이션 | 두 테이블을 모두 보존하고 차이를 직접 확인합니다 |
| 확인을 실행하지 못함: drain 또는 sync 실패, 타임아웃을 넘긴 읽기, 또는 따라잡지 못한 레플리카 | 권한(grant)을 고치거나, 레플리카 하나에 직접 연결하거나, --statement-timeout-s를 늘린 다음, 거부된 동작(--drop-pre-rebuild 또는 --rollback)을 다시 실행합니다 |
--rollback은 이전 테이블에 없는 행만 다시 복사합니다. 버전 컬럼이 있는 테이블에서는 이전 테이블의 최고 버전보다 높은 버전을 복사하고, 버전 컬럼이 없는 chunks에서는 이전 테이블에 없는 키를 복사합니다. 라이브 테이블의 경량 UPDATE 또는 DELETE, 또는 삭제 툼스톤은 키와 버전을 그대로 유지하며, 이전 테이블의 최고 버전보다 낮은 버전으로 기록된 행은 다시 복사되지 않습니다. 따라서 --rollback은 이런 변경을 잃게 됩니다. 이 명령은 교환 전에 위의 확인을 실행하고, 다음 단계가 --rollback이 아닌 모든 결과에 대해 아무것도 교환하지 않고 거부합니다(종료 코드 3). 이전 테이블의 병합을 다시 시작하므로, 롤백 복사본에서 끝나지 않은 뮤테이션은 그 뒤에 적용되며, 이어서 실행하는 --drop-pre-rebuild는 그 뮤테이션이 건드린 키를 한 버전에서 서로 다른 키로 보여 줍니다. 롤백 이후 새 레이아웃 복사본에서 끝나지 않은 ALTER UPDATE는 FINAL에서 보이지 않으며, 그래서 이 복사본의 뮤테이션도 집계 대상에 포함됩니다. 롤백이 성공하면 요약에 다음 단계가 표시됩니다. 쓰기 작업과 삭제를 계속 중지한 상태로 --drop-pre-rebuild --yes를 실행하세요. 이 명령은 새 레이아웃 복사본을 삭제하기 전에 두 테이블을 확인합니다. 두 번째 --rollback은 거부되며(종료 코드 3) 같은 단계를 안내합니다. 라이브 테이블이 더 이상 새 레이아웃이 아니기 때문입니다.
라이브 테이블에서 일어난 삭제는 해당 키를 롤백 복사본에만 남기므로, 첫 번째 행은 복사가 시작된 뒤 라이브 테이블에 뮤테이션이 없는 경우에만 --rollback을 안내합니다.
차이를 직접 확인하려면 쓰기 작업과 삭제를 중지한 상태로, 두 테이블이 서로 다르게 가진 키를 양쪽의 버전 컬럼과 함께 나열합니다. <version>은 테이블의 ReplacingMergeTree 버전 컬럼으로, version이며 memory_chunks와 entity_vectors에서는 created_at, conversation_embeddings에서는 ts입니다. <key>는 테이블의 정렬 키입니다.
<copy_vectors>와 <live_vectors>는 리빌드에서 지정한 벡터 컬럼(--columns)만 나열합니다. <columns>는 그 밖의 모든 컬럼이며 다른 벡터 컬럼도 포함하고, 각 컬럼은 양쪽에서 같은 이름으로 씁니다. 도구는 이 컬럼들을 저장된 그대로 해시합니다.
리빌드에서 지정한 컬럼은, 새 레이아웃 쪽(스왑 이후에는 라이브 테이블, 롤백 이후에는 복사본)에서는 컬럼 이름 그대로 씁니다. 이전 레이아웃 쪽에서는 리빌드가 쓰는 방식 그대로
if(length(<column>) = <dim>, CAST(<column> AS Array(BFloat16)), arrayResize(CAST([] AS Array(BFloat16)), <dim>, toBFloat16(0)))
로 씁니다. 여기서 <dim>은 코덱의 너비(새 레이아웃의 SHOW CREATE TABLE에 있는 Quantized(<method>, <dim>, 0))이며, 이렇게 하면 두 레이아웃이 같은 해시를 냅니다.
SELECT <key>, s.<version> AS copy_version, t.<version> AS live_version,
s.__present AS in_copy, t.__present AS in_live
FROM (SELECT <key>, <version>, cityHash64(tuple(<columns>, <copy_vectors>)) AS __hash,
1 AS __present FROM loom.<table>_pre_rebuild FINAL) AS s
FULL OUTER JOIN
(SELECT <key>, <version>, cityHash64(tuple(<columns>, <live_vectors>)) AS __hash,
1 AS __present FROM loom.<table> FINAL) AS t USING (<key>)
WHERE s.__hash != t.__hash
SETTINGS join_use_nulls = 0
버전 컬럼이 없는 테이블에서는 FINAL과 <version>을 빼고, 양쪽에서 count() AS n, sum(cityHash64(...)) AS __hash ... GROUP BY <key>를 읽습니다. 나열된 각 키의 전체 행을 두 테이블에서 읽고, 아직 적용되지 않은 뮤테이션이 있는지 system.mutations를 확인합니다. 그런 다음:
- 나열된 모든 키의 변경이 작성자의 의도대로 라이브 테이블에 있고, 확인에서 집계한 뮤테이션이 라이브 테이블에 모두 적용되었다면,
DROP TABLE loom.<table>_pre_rebuild SYNC로 복사본을 삭제합니다. - 그렇지 않으면 윈도우 안에서 복사본에만 있는 각 행을 라이브 테이블로 복사합니다
(
INSERT INTO loom.<table> (<all columns>) SELECT <all columns> FROM loom.<table>_pre_rebuild FINAL WHERE (<key>) IN (...). 한 버전에서는 마지막에 삽입한 행이 우선합니다). 읽기를 다시 실행해 라이브 테이블이 유지해야 할 변경만 나열될 때까지 반복한 다음 복사본을 삭제합니다.<all columns>에서는 MATERIALIZED 컬럼과 ALIAS 컬럼을 제외합니다. INSERT가 이를 거부하기 때문입니다. 스왑 이후 라이브 테이블은 코덱이 적용되어 있어 빈 벡터나 다른 너비의 벡터를 거부하므로,SELECT에서 리빌드에서 지정한 각 컬럼을 리빌드가 쓰는 방식 그대로 씁니다.if(length(<column>) = <dim>, CAST(<column> AS Array(BFloat16)), arrayResize(CAST([] AS Array(BFloat16)), <dim>, toBFloat16(0))) AS <column>.
직접 삭제하면 그 테이블에만 있는 내용의 유일한 사본이 사라지므로, 반드시 읽기 확인을 마친 뒤에 수행하세요.
디스크 압박 관리
Loom 호스트에서:
- Docker의 JSON 로그 크기를 제한하세요. 한 줄마다 스택 트레이스를 기록하는 컨테이너는 디스크를 빠르게 채울 수 있습니다.
/etc/docker/daemon.json에log-opts를 설정하세요(예:max-size100m ×max-file5). - 빌드 캐시와 dangling 이미지를 제거하세요.
docker builder prune과docker image prune을 사용합니다. - 컨테이너는 prune하지 마세요.
docker container prune은 중지된 컨테이너를 제거하는데, 무중단 쌍에서는 중지된 색상이 곧 롤백 대상입니다(백업 및 복구). - 코드 미러를 주시하세요.
var/code_repos에는 인덱싱된 저장소마다 bare clone이 하나씩 들어 있습니다. 저장소를 폐기하면 다른 항목이 해당 미러를 사용하지 않고 미러가LOOM_CODE_REPOS_ROOT아래에 있는 경우에 한해 미러가 삭제됩니다. 운영자가 다른 위치에 둔 미러는 그대로 남습니다. - 진단 출력은 작게 유지하세요. 디스크가 가득 차면 임시 파일을 쓰는 명령도 실패합니다. 진단 결과는
/dev/shm같은 메모리 기반 경로에 기록하세요.
ClickHouse에서:
SELECT table, formatReadableSize(sum(bytes_on_disk)) AS size
FROM system.parts WHERE active AND database = 'loom'
GROUP BY table ORDER BY sum(bytes_on_disk) DESC LIMIT 10;
SELECT name, formatReadableSize(free_space) FROM system.disks;
대량 삭제 후에는 머지가 버전을 정리하도록 두거나, 코드 벡터 테이블을 컴팩션하거나, 테이블별 보존 정책을 선택적으로 적용하세요. 증상부터 찾아보는 설명은 문제 해결에 있습니다.