Cloudwiki/설정/RAG

# 개요

RAG(Cloudflare AI Search, 구 AutoRAG) 보조 검색은 기본 본문 검색(D1 FTS)을 **보완**하는 선택적 플러그인입니다. 정확한 문자열 매칭이 아니라 **의미가 가까운 문서**를 찾아주므로, 표현이 조금 달라도 관련 문서를 검색할 수 있습니다.

- 배포 시점 환경변수 `RAG_SEARCH_ENABLED` 로 켜고 끕니다.
- 켜면 문서가 변경될 때마다 **현행 본문**을 인덱싱 전용 R2 버킷에 즉시 미러링합니다.
- `/search` 페이지에 **RAG 검색 체크박스**가, MCP 도구에 **search_rag** 가 노출됩니다.
- **제목 검색은 그대로 유지**되고, 체크 시 **본문 검색만** RAG로 전환됩니다.

> RAG 플러그인은 선택 사항입니다. 켜지 않아도 위키는 기존 FTS 검색으로 정상 동작합니다.

# 동작 방식

- **인덱싱 시점**: 별도 cron 대조 없이 문서 생성·수정·이동·삭제 시점에 즉시 R2 미러를 갱신합니다. 미러링 실패는 본문 저장을 막지 않습니다(best-effort).
- **권한 처리**: 비공개 문서를 포함해 **모든 문서를 인덱싱**하되, 검색 결과를 반환한 뒤 **비공개·삭제 문서를 사후 필터링**해 사용자 권한에 맞는 결과만 제공합니다. `/search` 와 MCP 모두 동일하게 동작합니다.
- **R2 ↔ AI Search 연결**: 미러링은 코드가 담당하고, 그 R2 버킷을 인덱싱 대상으로 등록하는 일은 Cloudflare 대시보드에서 한 번만 수동 설정하면 이후 자동 관리됩니다.

# 사전 준비

대시보드(https://dash.cloudflare.com)에서 다음을 준비합니다.

## 인덱싱 전용 R2 버킷 생성

`R2 Object Storage` 에서 본문 미러링 전용 버킷을 하나 새로 만듭니다(미디어용 기존 버킷과 별도). 예: `cloudwiki-rag`.

> 기존 미디어 버킷(`MEDIA`)과 **반드시 다른 버킷**을 사용하세요. RAG 버킷에는 검색용 본문만 평문으로 들어갑니다.

## AI Search 인스턴스 생성

대시보드의 `AI` → `AI Search`(구 AutoRAG)로 이동해 인스턴스를 생성하고, **데이터 소스로 위에서 만든 R2 버킷**을 지정합니다. 이때 정한 **인스턴스 이름**을 기억해 둡니다(아래 `RAG_AUTORAG_NAME` 과 일치해야 합니다).

> 인덱싱 임베딩·동기화 주기 등 세부 옵션은 AI Search 인스턴스 설정에서 관리합니다. 버킷에 객체가 채워지면 자동으로 인덱싱됩니다.

# wrangler.toml 설정

`wrangler.toml` 에 다음 바인딩과 변수를 설정합니다(`wrangler example.toml` 에 더미값이 포함되어 있습니다).

```toml
# 인덱싱 전용 R2 버킷
[[r2_buckets]]
binding = "RAG_BUCKET"
bucket_name = "cloudwiki-rag"   # 생성한 버킷 이름

# Workers AI 바인딩 (AI Search 질의용)
[ai]
binding = "AI"

[vars]
RAG_SEARCH_ENABLED = "true"        # 플러그인 활성화
RAG_AUTORAG_NAME = "cloudwiki-rag" # AI Search 인스턴스 이름
```

- `RAG_SEARCH_ENABLED` 가 `"true"` 이고 `RAG_BUCKET`·`AI` 바인딩·`RAG_AUTORAG_NAME` 이 모두 구성돼야 검색 기능이 동작합니다.
- 값이 비거나 `"false"` 면 체크박스·MCP 도구가 숨겨지고 미러링도 동작하지 않습니다(기존 FTS만 사용).

> `wrangler.toml` 은 언제든 수정할 수 있으며, main 브랜치에 반영되면 1~2분 내 자동 배포됩니다.

# 초기 백필

미러링은 **플러그인을 켠 이후의 변경부터** 적용됩니다. 따라서 켜기 전부터 있던 기존 문서는 다음 편집 전까지 인덱스에 없습니다. 도입 직후 한 번, 전 문서를 인덱스에 채워 넣어야 합니다.

`문서 대량 관리`(`/admin-bulk-manage`, **최고 관리자 전용**) 페이지의 **RAG 인덱스 백필** 카드에서 **백필 시작** 을 누르면, 전 문서의 현행 본문이 R2 버킷에 일괄 미러링됩니다.


백필 동작 참고
- ACL과 무관하게 전 문서를 인덱싱합니다(비공개 포함). 검색 시점에 권한에 따라 비공개·삭제 문서가 걸러집니다.
- 백그라운드 잡으로 진행되며 페이지를 닫아도 계속 실행됩니다. 중지/재개가 가능합니다.
- 도입 시 1회만 실행하면 됩니다. 이후 변경은 자동으로 미러링됩니다.



# 사용법

## 검색 페이지

`/search` 의 필터 바에 **RAG 검색** 체크박스가 나타납니다(플러그인 활성 시). 체크하면 본문 검색이 FTS 대신 AI Search로 전환됩니다. 검색 범위가 `제목+본문` 이면 제목/슬러그 매칭은 그대로 두고 본문만 RAG로 검색해 병합합니다.

## MCP 도구

플러그인 활성 시 MCP에 `search_rag` 도구가 노출됩니다. 자연어 질의로 본문을 의미 검색하며, 응답에는 `slug`·`title`(표시 전용)·`score`·`snippet` 이 포함됩니다. 비공개·삭제 문서는 호출자 권한에 따라 제외됩니다.

> 다른 문서 호출·링크에는 항상 `slug` 를 사용하세요. `title` 은 표시 전용입니다.

# 비활성화

`RAG_SEARCH_ENABLED` 를 `"false"` 로 두면 체크박스·MCP 도구가 숨겨지고 미러링이 중단됩니다. 이미 만들어진 R2 미러 객체와 AI Search 인스턴스는 남아 있으므로, 완전히 정리하려면 대시보드에서 R2 버킷 객체와 AI Search 인스턴스를 직접 삭제하세요.

> 플러그인을 꺼도 영구 삭제(하드 삭제) 시 해당 문서의 R2 미러 정리는 계속 수행되어 고아 객체가 남지 않습니다.