RAG 도구

RAG 도구 (RAG Tool)

에이전트가 응답 전에 문서를 검색해 관련 정보를 찾는 방법을 설명해요. 검색 증강 생성(RAG)으로 지식 베이스를 연결할 수 있어요.

출처: 문서

본문

rag 도구셋은 에이전트가 응답 전에 문서를 검색해 관련 정보를 찾게 해 줘요. 지식 베이스는 구성 상단의 rag: 아래에 한 번 선언하고, 어떤 에이전트에서든 type: rag, ref: <name>으로 참조해요. Docker Agent는 다음을 지원해요:

  • 백그라운드 인덱싱 — 파일이 자동으로 인덱싱되고 변경 시 재인덱싱돼요
  • 여러 전략 — 시맨틱 임베딩, BM25 키워드 검색, LLM 강화 검색
  • 하이브리드 검색 — 결과 융합으로 전략 결합, 최상의 결과
  • 리랭킹 — 특화 모델로 결과 재채점해 관련성 개선

RAG는 문서 집합이 인라인으로 넣기엔 너무 크거나, 턴/세션을 넘어 반복적으로 질의될 때 택하는 전략이에요 — @//attach 첨부 및 프롬프트 파일과 어떻게 비교되는지는 Choosing a Large-Input Strategy 문서를 참고하세요.

빠른 시작

rag:
  my_docs:
    tool:
      description: "Technical documentation"
    docs: [./documents, ./some-doc.md]
    strategies:
      - type: chunked-embeddings
        embedding_model: openai/text-embedding-3-small
        database: ./docs.db
        vector_dimensions: 1536

agents:
  root:
    model: openai/gpt-4o
    instruction: |
      You have access to a knowledge base. Use it to answer questions.
    toolsets:
      - type: rag
        ref: my_docs

검색 전략

Chunked Embeddings (시맨틱 검색)

임베딩 모델로 의미상 비슷한 내용을 찾아요. 의도, 동의어, 의역 이해에 가장 좋아요.

strategies:
  - type: chunked-embeddings
    embedding_model: openai/text-embedding-3-small
    database: ./vector.db
    vector_dimensions: 1536
    similarity_metric: cosine_similarity
    threshold: 0.5
    limit: 10
    embedding_batch_size: 50
    chunking:
      size: 1000
      overlap: 100

Semantic Embeddings (LLM 강화)

각 청크를 임베딩하기 전에 LLM으로 시맨틱 요약을 생성해서 의미와 의도를 포착해요. 코드 검색과 구현 이해에 가장 좋아요.

strategies:
  - type: semantic-embeddings
    embedding_model: openai/text-embedding-3-small
    vector_dimensions: 1536
    chat_model: openai/gpt-4o-mini
    database: ./semantic.db
    ast_context: true # AST 메타데이터 포함
    chunking:
      size: 1000
      code_aware: true # AST 인식 청킹

참고 트레이드오프 시맨틱 임베딩은 더 높은 품질의 검색을 제공하지만 더 느린 인덱싱(청크당 LLM 호출)과 추가 API 비용이 들어요.

BM25 (키워드 검색)

BM25 알고리즘을 사용하는 전통적인 키워드 매칭. 정확한 용어, 기술 전문 용어, 코드 식별자에 가장 좋아요.

strategies:
  - type: bm25
    database: ./bm25.db
    k1: 1.5 # 용어 빈도 포화
    b: 0.75 # 길이 정규화
    threshold: 0.3
    limit: 10
    chunking:
      size: 1000
      overlap: 100

하이브리드 검색

최상의 결과를 위해 여러 전략을 결합해요. 전략은 병렬로 실행되고 결과가 융합돼요:

rag:
  hybrid:
    docs: [./docs]
    strategies:
      - type: chunked-embeddings
        embedding_model: openai/text-embedding-3-small
        database: ./vector.db
        vector_dimensions: 1536
        limit: 20
        chunking: { size: 1000, overlap: 100 }
      - type: bm25
        database: ./bm25.db
        limit: 15
        chunking: { size: 1000, overlap: 100 }
    results:
      fusion:
        strategy: rrf # Reciprocal Rank Fusion
        k: 60
      deduplicate: true
      limit: 5

융합 전략

전략 용도 설명
rrf 일반용(권장) Reciprocal Rank Fusion — 순위 기반, 점수 정규화 불필요
weighted 알려진 성능 특성 전략을 다르게 가중(예: embeddings: 0.7, BM25: 0.3)
max 같은 점수 척도 어느 전략에서든 최대 점수 취함

리랭킹

특화 모델로 검색된 문서를 다시 채점해 관련성을 높여요:

results:
  reranking:
    model: openai/gpt-4o-mini
    top_k: 10 # 상위 10개만 리랭킹
    threshold: 0.3 # 리랭킹 후 최소 점수
    criteria: |
      Prioritize official documentation over blog posts.
      Prefer recent information and practical examples.
  limit: 5

지원되는 리랭킹 프로바이더: DMR(네이티브 /rerank 엔드포인트), OpenAI, Anthropic, Gemini.

코드 인식 청킹

소스 코드의 경우 AST 기반 청킹을 활성화해 함수와 메서드를 온전히 유지하세요:

chunking:
  size: 2000
  code_aware: true # tree-sitter로 AST 기반 청킹

참고 언어 지원 현재 Go(.go) 파일을 지원해요. 더 많은 언어가 추가될 예정이에요. 지원되지 않는 파일 유형에는 일반 텍스트 청킹으로 폴백해요.

RAG 디버깅

검색 세부 정보를 보려면 디버그 로깅을 활성화하세요:

$ docker agent run config.yaml --debug --log-file debug.log

로그 태그를 찾아보세요: [RAG Manager], [Chunked-Embeddings Strategy], [BM25 Strategy], [RRF Fusion], [Reranker].

영구 모델 오류는 일찍 중단돼요. 임베딩 모델, 시맨틱 LLM 모델, 리랭킹 모델이 영구 오류(HTTP 400, 401, 404, 429 — 잘못된 구성, 잘못된 인증, 알 수 없는 모델, 속도 제한)를 반환하면 Docker Agent는 운이 없는 요청을 재시도하는 대신 모델 구성이 잘못된 것으로 취급하고 즉시 중지해요:

  • 인덱싱 — 첫 영구 실패(429 포함) 후 전체 인덱싱 실행이 중단돼요. 오류가 로그에 표시되어 모델 이름이나 API 키가 잘못됐을 때 조용히 불완전한 결과를 만들기보다 즉시 알 수 있어요.
  • 리랭킹 — 영구 오류(429 포함)는 매니저 수명 동안 리랭커를 영구히 비활성화해요. 이후 질의는 리랭킹 없는 결과로 폴백해요. 일시적 오류(5xx, 타임아웃)만 폴백하고 다음 질의에서 재시도해요.

팁 예시 GitHub 저장소의 RAG 예시에서 완전한 실행 가능한 구성을 확인하세요.

구성 참조

최상위 RAG 필드

필드 타입 기본값 설명
docs []string — 문서 경로/디렉터리(전략 간 공유)
description string — 이 RAG 소스에 대한 사람이 읽을 수 있는 설명
respect_vcs boolean true 문서 인덱싱 시 .gitignore 파일 존중
strategies []object — 검색 전략 구성 배열
results object — 후처리: 융합, 리랭킹, 중복 제거, 최종 한도

Chunked-Embeddings 전략

필드 타입 기본값 설명
embedding_model string — 필수. 임베딩 모델 참조
database string — 로컬 SQLite 데이터베이스 경로
vector_dimensions int — 임베딩 차원(예: text-embedding-3-small은 1536)
similarity_metric string cosine_similarity 유사도 지표
threshold float 0.5 최소 유사도 점수(0–1)
limit int 5 이 전략의 최대 결과
embedding_batch_size int 50 임베딩 요청당 청크 수
max_embedding_concurrency int 3 최대 동시 임베딩 요청
chunking.size int 1500 청크 크기(문자)(code_aware 설정 시 4000)
chunking.overlap int 75 청크 간 겹침(문자)
chunking.code_aware bool false AST 기반 청킹(Go 파일만)

Semantic-Embeddings 전략

필드 타입 기본값 설명
embedding_model string — 필수. 임베딩 모델 참조
chat_model string — 필수. 시맨틱 요약 생성용 LLM
vector_dimensions int — 필수. 임베딩 차원
database string — 로컬 SQLite 데이터베이스 경로
semantic_prompt string (내장) 커스텀 프롬프트 템플릿(${path}, ${content}, ${ast_context})
ast_context bool false 프롬프트에 tree-sitter AST 메타데이터 포함
threshold float 0.5 최소 유사도 점수(0–1)
limit int 5 최대 결과
max_indexing_concurrency int 3 최대 동시 파일 인덱싱
chunking.size int 1500 청크 크기(문자)(code_aware 설정 시 4000)
chunking.overlap int 75 청크 간 겹침
chunking.code_aware bool false AST 기반 청킹

BM25 전략

필드 타입 기본값 설명
database string — 로컬 SQLite 데이터베이스 경로
k1 float 1.5 용어 빈도 포화(1.2–2.0 권장)
b float 0.75 길이 정규화(0–1)
threshold float 0.0 최소 BM25 점수
limit int 5 최대 결과
chunking.size int 1500 청크 크기(문자)
chunking.overlap int 75 청크 간 겹침

결과 (후처리)

필드 타입 기본값 설명
fusion.strategy string rrf 융합 방법: rrf, weighted, max
fusion.k int 60 RRF 순위 상수
deduplicate bool true 중복 결과 제거
limit int 15 최종 결과 수
include_score bool false 결과에 관련성 점수 포함
return_full_content bool false 매칭된 청크 대신 전체 문서 내용 반환
reranking.model string — 리랭킹 모델 참조
reranking.top_k int (limit) 상위 K 결과만 리랭킹. 설정 시 결과 limit 기본값
reranking.threshold float 0.5 리랭킹 후 최소 관련성 점수
reranking.criteria string — 리랭킹 모델용 커스텀 관련성 지침

더 알아보기 (Learn more)