지식 베이스
지식 베이스는 에이전트의 답을 근거 있게 느끼게 만드는 것입니다 — LLM 은 매 턴 당신의 runbook, 과거 postmortem, 팀 문서를 검색할 수 있으므로 학습 데이터에서 추측할 필요가 없습니다.
저장 형태
하나의 벡터 저장소, 세 소스 타입.
| Source type | 출처 | 읽기 전용? |
|---|---|---|
vault | 내장 ongridio/vault 플레이북 모음 (2026-05-29 기준 96 markdown 문서) | 예 |
repo | 등록한 Git URL — 공개 HTTPS 또는 저장소별 identity 를 통한 SSH | 아니오 (설정 편집 + 재동기화) |
upload | SPA 의 /knowledge 페이지를 통한 직접 업로드 (md / txt / pdf / docx) | 아니오 (행 편집 / 삭제) |
manual | 인라인 에디터로 markdown 붙여넣기 | 아니오 |
네 타입 모두 하나 의 Qdrant 컬렉션 (ongrid_knowledge) 과 하나 의 임베딩 모델을 공유. 검색 히트는 source_type payload 필드를 반환하여 UI 가 올바른 "vault 에서" / "당신의 저장소에서" 배지를 렌더링하게.
ADR-028 — 지식 소스, 계층화
하나의 컬렉션인 이유: 대안 (소스 타입당 하나의 컬렉션) 은 LLM 이 커버리지를 얻기 위해 질문당 N 번 검색을 호출해야 했고 도구 호출 예산을 폭파했습니다. 하나의 컬렉션 + source_type 필터는 하나의 쿼리로 같은 격리를 얻습니다.
Qdrant 클라이언트
좁은 표면, internal/manager/biz/knowledge/usecase.go:62 에:
type QdrantClient interface {
EnsureCollection(ctx context.Context, name string, dim int) error
EnsurePayloadIndex(ctx context.Context, collection, field, schema string) error
Upsert(ctx context.Context, collection string, points []qdrantx.Point) error
DeleteByFilter(ctx context.Context, collection string, mustMatch map[string]any) error
DeleteByID(ctx context.Context, collection string, id uint64) error
GetPoints(ctx context.Context, collection string, ids []uint64) ([]qdrantx.SearchHit, error)
Search(ctx context.Context, collection string, vector []float32, opts qdrantx.SearchOpts) ([]qdrantx.SearchHit, error)
Scroll(ctx context.Context, collection string, opts qdrantx.ScrollOpts) (*qdrantx.ScrollResult, error)
}프로덕션에서 internal/pkg/qdrantx 가 받침, 테스트에서 가짜 가능. Qdrant 는 docker-compose 에 출하; 외부 Qdrant 는 ONGRID_QDRANT_URL 를 통해 지원.
Vault
Vault 는 사전 큐레이션된 진단 플레이북을 출하하는 공개 git 저장소 (인증 없음). 다루는 주제 (2026-05-29 기준):
- 네트워크: DNS / TCP / TLS / HTTP 디버깅 레시피.
- Kubernetes: pod / node / kubelet 증상에서 원인 매핑.
- Linux: 프로세스 / 메모리 / 디스크 / journald investigation 경로.
- 데이터베이스: MySQL slow-log 분류, PostgreSQL 복제 지연.
- 진단: 70+ 증상 키 플레이북.
ADR-029 가 클라우드 동기화 추가: 매니저가 스케줄 (기본 24h, SPA 설정으로 구성 가능) 로 최신 vault 를 풀하고 변경 시 재 임베딩. 디스크 체크아웃은 /var/lib/ongrid/repos/<vault_id>/ 아래에 살고; qdrant 포인트는 source=vault 로 태그되어 Sync 는 vault 포인트만 삭제, 자체는 절대 삭제 안 함.
Vault 를 자체 저장소로 다루지 마세요
Vault 는 내장 소스 — /knowledge/repos CRUD 페이지에 절대 나타나지 않습니다. 코드는 이를 게이트하기 위해 isBuiltinVault() / is_builtin 을 사용; ongridio/vault 를 substring 매칭하지 마세요 (반복 함정 피드백 참고).
자체 저장소
POST /v1/knowledge/repos 와 { url, name } body 가 git 저장소 등록. 다음 sync 틱에서 매니저는:
/var/lib/ongrid/repos/<id>/로git clone --depth=1(또는 디렉터리가 이미 존재하면git pull)..md/.txt/.rst/.yaml/.yml/.toml/.json파일용으로 트리 워크.- 구성된 임베딩 모델로 각 파일 임베딩.
- 해당 저장소의 포인트 셋 (
source=repo,repo_id=<id>) 을 원자적으로 교체.
SSH 인증
저장소별 identity, ssh_identities 테이블과 SPA 의 /knowledge/identities 페이지로 관리. Repository 행은 provider 필드를 운반하지 않음 — identity 테이블이 git 자격 증명의 단일 출처 (ADR-023).
GIT_SSH_COMMAND 가 sync 별로 identity 의 키 파일을 가리키도록 설정되어 각 저장소의 clone 이 $HOME/.ssh/ 를 오염시키지 않고 자체 키를 사용.
HTTPS 인증
공개 HTTPS 저장소는 인증 없이 clone. 비공개 HTTPS 인증은 보류: 원래 GitHub-PAT 경로는 SSH 가 현실적인 사용 사례를 커버하면서 제거됨. ADR-018 의 RepoFetcher 가 안착할 때까지 비공개는 SSH 사용.
업로드
/knowledge/upload 페이지가 수락:
| Format | Extractor |
|---|---|
.md, .txt | 원시 읽기 + 청크 |
.pdf | docextract (internal/pkg/docextract) |
.docx | docextract |
각 업로드는 knowledge_docs 의 행과 source=upload 인 qdrant 포인트 가 됨. "Organization knowledge" 트리에서 행별 인라인 편집과 삭제 동작.
검색
LLM 은 query_knowledge BaseTool 을 얻음 — 스키마는 query_knowledge_basetool.go. Args: query, 선택 source_type 필터, 선택 top_k. 반환: {score, source, title, snippet, url?} 히트 리스트.
Coordinator persona 는 "어떻게 X 하나" / "왜 X 가 발생하나" / "Y 에 대한 runbook 이 뭐야" 질문에 일찍 이를 호출하라고 안내 받음 — 하나의 지식 검색 비용은 플레이북이 이미 가졌던 같은 답에 도달하는 5 도구 investigation 보다 훨씬 낮습니다.
채팅 UI 도 Quick Action 버튼 "Search knowledge" 를 노출하여 운영자가 채팅을 거치지 않고 같은 인덱스를 칠 수 있게 합니다.