지식 문서를 만들고 선택적으로 RAG 도구 준비하기

LLM은 조직 내부의 최신 규정이나 이 코스에서 만든 정책을 스스로 알지 못합니다. RAG(Retrieval-Augmented Generation)는 질문과 관련된 지식 청크를 먼저 찾고, 그 내용을 LLM에 전달해 답변의 근거로 사용합니다.

이번 레슨에서는 agent_builder_policy 지식과 response_policy 수동 문서를 만듭니다. 이어서 도구 편집기의 지식 삽입 기능이 만드는 @use_rag 바인딩을 살펴봅니다.

준비 상태 확인하기

RAG 도구를 끝까지 실행하려면 같은 컬렉션에 다음 리소스가 모두 필요합니다.

• 검색할 지식과 문서
• 시맨틱 검색을 사용한다면 임베딩 모델
• RAG가 검색 결과로 답변을 만들 때 사용할 등록된 LLM 모델

왼쪽 사이드바의 AI → LLM 모델에서 실습 컬렉션에 등록된 모델이 있는지 먼저 확인합니다. 등록된 모델이 없다면 지식과 문서까지는 만들 수 있지만, @use_rag 도구 테스트와 에이전트 배포는 진행할 수 없습니다.

지식 만들기

1. 왼쪽 사이드바에서 AI → 지식 관리를 선택합니다.
2. 오른쪽 위의 생성을 선택합니다.
3. 지식 만들기 화면의 기본 정보에 다음 값을 입력합니다.

검색 옵션 선택하기

검색 옵션은 지식을 어떤 방식으로 색인하고 검색할지 정합니다.

• 시맨틱 검색 — 문장의 의미가 비슷한 청크를 찾습니다. 임베딩 모델 선택이 필요합니다.
• 키워드 검색 — 역색인에서 정확한 단어나 구문을 찾습니다.
• 지식 그래프 — 문서에서 엔티티와 관계를 추출해 탐색합니다.

임베딩 모델을 선택할 수 있다면 시맨틱 검색을 사용하고 KoE5 또는 조직에서 제공하는 다른 임베딩 모델을 선택합니다. 임베딩 모델이 없다면 키워드 검색만 선택해 지식과 수동 문서를 먼저 만들 수 있습니다. 다만 이 경우 아래의 벡터 RAG 도구 테스트는 모델이 준비될 때까지 진행하지 않습니다.

선택을 마쳤으면 화면 아래의 생성을 선택합니다. 지식 상세 화면으로 이동합니다.

수동 문서와 첫 청크 만들기

지식 상세 화면에는 문서, 채팅, 검색, 설정, 공유 및 권한 탭이 있습니다.

1. 문서 탭에서 문서 추가를 선택합니다.
2. 수동 문서를 선택합니다.
3. 수동 문서 추가 화면에서 다음 값을 입력합니다.

4. 초기 청크에 다음 내용을 입력합니다.

# 응답 근거 작성 원칙

## POLICY-01 근거 표시
지식 검색 결과를 사용한 답변에는 근거 코드 `POLICY-01`을 표시합니다.

## POLICY-02 검색 결과 없음
관련 근거를 찾지 못했다면 추측하지 말고 `근거를 찾지 못했습니다`라고 답변합니다.

5. 문서 만들기를 선택합니다.
6. 문서 상세 화면에서 청크 수가 1이고 두 정책의 내용이 보이는지 확인합니다.

파일이나 웹 페이지도 추가할 수 있지만 이번 코스에서는 입력 결과를 바로 확인할 수 있는 수동 문서를 사용합니다. 파일·웹 문서는 색인 작업이 완료될 때까지 기다린 뒤 사용해야 합니다.

RAG 도구에서 지식 바인딩 만들기

등록된 LLM 모델이 있는 경우에만 다음 단계를 진행합니다. 모델이 없다면 이 절부터 테스트하고 에이전트에 연결하기까지 건너뛰어도 4강을 완료한 것입니다.

1. AI → 도구 → 생성을 선택합니다.
2. 이름을 course_search_policy, 별칭을 응답 정책 검색 도구, 설명을 에이전트 응답 정책에서 관련 근거를 검색합니다.로 입력하고 같은 컬렉션을 선택합니다.
3. 필수 문자열 파라미터 query를 추가합니다.
4. 소스 코드 오른쪽 위의 책 모양 지식 버튼을 선택합니다.
5. 다음 값을 선택합니다.

6. 삽입을 선택합니다.

위 화면처럼 모델과 지식베이스 선택이 비어 있고 삽입이 비활성화되어 있다면, 현재 컬렉션에 사용할 수 있는 LLM 모델 또는 시맨틱 검색 지식이 없는 상태입니다. 조직의 모델 관리자가 같은 컬렉션에 모델을 등록한 뒤 다시 엽니다.

편집기에 다음 형태의 데코레이터를 삽입합니다. @use_rag에는 retriever="vector"를 추가하고, model과 knowledge는 화면에서 선택한 실제 값으로 채웁니다.

import asyncio

@use_rag("policy_rag", strategy="vector", retriever="vector", model="test_llm", knowledge="")
def execute(query: str) -> dict:
    async def run_rag():
        await policy_rag._retriever.initialize()
        return await policy_rag.execute(
            query,
            top_k=3,
            score_threshold=0.0,
        )

    result = asyncio.run(run_rag())
    return {
        "answer": result.answer,
        "sources": policy_rag.retrieved_sources,
    }

예시의 test_llm은 실제 검증에 사용한 등록 모델 이름입니다. 다른 이름으로 모델을 등록했다면 model을 해당 이름으로 바꿉니다. knowledge=""에는 화면에서 선택한 지식의 실제 ID를 입력합니다. 현재 지식 삽입 폼은 retriever를 따로 선택하지 않으므로 삽입 후 직접 추가해야 합니다. 이 값을 생략하면 RAG 전략에 실제 검색기를 전달하지 못해 도구 테스트가 실패할 수 있습니다.

현재 벡터 RAG 검색기는 실행 전에 명시적으로 초기화해야 합니다. await policy_rag._retriever.initialize()를 생략하면 VectorRetriever not initialized. Call initialize() first. 오류가 발생합니다. 초기화와 policy_rag.execute(...)는 같은 비동기 함수 안에서 실행합니다.

runner가 호출하는 최상위 진입점은 일반 def execute()여야 합니다. async def execute()로 작성하면 runner가 coroutine을 자동으로 기다리지 않아 <coroutine object execute ...>가 결과로 표시될 수 있습니다. 내부의 비동기 policy_rag.execute(...)만 asyncio.run()으로 실행합니다.

테스트하고 에이전트에 연결하기

1. 테스트 실행의 입력값에 다음 JSON을 입력합니다.

{
  "query": "검색 결과가 없을 때 어떻게 답변해야 하나요?"
}

2. 실행을 선택합니다.
3. 성공 결과의 answer와 sources에서 POLICY-02 내용을 확인합니다.
4. 저장한 뒤 에이전트 빌더 실습의 기능 구성 → 도구 → 전체 보기에서 응답 정책 검색 도구를 선택하고 저장합니다.

도구의 예시에는 설명과 함께 { "query": "검색 결과가 없으면 어떻게 답변해야 하나요?" }를 추가합니다. 에이전트의 시스템 지침에도 “도구를 호출할 때 사용자의 질문 전체를 query 문자열로 전달한다”라고 명시합니다. 일부 OpenAI 호환 모델은 예시나 지침이 없으면 필수 query를 누락할 수 있습니다.

requires model 또는 등록 모델을 찾지 못했다는 오류가 나오면 코드 문제가 아니라 모델 선행 조건이 충족되지 않은 상태입니다. AI → LLM 모델에서 같은 컬렉션의 모델을 등록한 뒤 다시 테스트합니다.

자가 점검

• agent_builder_policy 지식이 이전 리소스와 같은 컬렉션에 있습니다.
• 지식 생성 시 사용할 검색 방식과 필요한 모델을 확인했습니다.
• response_policy 수동 문서에 청크 1개가 보입니다.
• RAG의 knowledge 값이 지식 이름이 아니라 화면에서 삽입된 실제 ID입니다.
• strategy에 맞는 retriever 인자를 삽입 후 추가했습니다.
• 벡터 검색기를 policy_rag._retriever.initialize()로 먼저 초기화했습니다.
• 최상위 진입점이 일반 def execute()입니다.
• 비동기 policy_rag.execute(...)를 asyncio.run()으로 실행합니다.
• 등록 모델이 없다면 실패 원인과 다음 행동을 구분할 수 있습니다.

다음 레슨

허용 목록 도구를 만들어 에이전트가 처리할 작업 범위를 명시합니다.