지식 베이스 구축 및 채우기

원칙 — 먼저 기반을 잡고, 그다음 검증한다. 지식베이스(MKB)는 힌트가 아닌, 반드시 따라야 할 소스입니다. instructions에서 그 범위를 설정하고, 이를 신뢰하기 전에 실제 질문이 검색되는지 반드시 확인하십시오 — 검색 결과가 비어 있다면 에이전트는 "다루지 않음"이라고 답합니다. 더 자세한 내용은 디자인 원칙을 참조하십시오.

마운트된 지식베이스는 매 턴마다 자동 검색됩니다 — 모델이 검색할지 여부를 결정하지 않습니다. 관련성은 벡터 거리를 기준으로 합니다. 이는 의도적인 설계입니다: KB는 선택적 도구가 아닌, 반드시 따라야 할 소스입니다.

1. 생성하기

create_knowledge_base(
  name="Company policy",
  description="Mortgage policy and rates, effective 2026 — not car or personal loans",  # routes questions here
  instructions="Authoritative current mortgage policy; overrides any industry norm. "
               "Covers home mortgages only; for car or personal loans, say so and hand off.",  # for the model
)

이름은 생성 시 URL 안전 슬러그로 정규화됩니다 — "Company policy"는 company-policy로 반환됩니다. 이후 모든 작업(add_knowledge_text(kb_name=…), search_knowledge_base(kb_name=…), 에이전트에 연결 등)에는 이 반환된 이름을 사용하십시오. 나중에 원래의 띄어쓰기가 있는 이름을 입력하면 404 오류가 발생합니다.

2. description 작성 — 이것이 질문을 이 베이스로 라우팅합니다

description은 캡션이 아닙니다. 매 답변 전에 플랫폼은 연결된 모든 베이스의 설명을 읽고 이 질문에 어떤 베이스가 필요한지 결정합니다 — 그리고 그중 어느 것도 해당되지 않으면 검색을 전혀 수행하지 않습니다. 세 개의 베이스가 있는 에이전트는 방문자가 "안녕"이라고 말했을 때조차 매 턴마다 세 번의 벡터 검색을 수행하고 세 세트의 발췌문을 프롬프트에 주입합니다.

따라서 모호하거나 빈 설명을 가진 베이스는 검색되어서는 안 될 때 검색되고, — 더 나쁘게도 — 검색되어야 할 때 누락됩니다. 이러한 실패는 스스로를 알리지 않습니다: 첫 번째는 관련 없는 인용문이 포함된 느린 답변으로 나타나고, 두 번째는 "그에 대한 정보가 없습니다"로 나타납니다.

방문자가 사용할 언어로 한 줄을 작성하십시오. 주제를 명시합니다:

✅ "Country-by-country medical device registration requirements"
✅ "Regulatory change news by country and authority, 2022–2026 — what changed and when"
✅ "Selpercatinib — for lung and thyroid cancer"
 
❌ "Knowledge base"                ← routes nothing
❌ "Imported from the website"     ← says where it came from, not what is in it
❌ "Sandbox test, safe to delete"  ← says why it exists, not what is in it

중요한 것은 길이가 긴 것이 아니라 다른 베이스들과 구별되는 것입니다. 9개의 베이스(8개의 약물과 회사 프로필, 각각 한 줄, 단어 수 12개 미만)를 가진 테넌트는 10개 중 10개 질문을 올바르게 라우팅합니다. "폐암 및 갑상선암용"과 "IgA 신병증용"은 절대 혼동될 수 없기 때문입니다. 측정된 것이지, 가정된 것이 아닙니다.

두 베이스가 겹치는 경우에만 경계를 추가하십시오. 제품 페이지와 뉴스 아카이브가 모두 동일한 주제에 대해 언급하는 경우, 각각이 무엇인지 명시하십시오 — "…— 가격 또는 회사 정보 제외"가 아카이브가 가격 질문에 답하는 것을 방지합니다. 베이스들이 이미 명확하게 구별되는 경우, 경계 절은 아무런 이점을 제공하지 못합니다.

이 한 줄은 콘솔 목록에도 표시되지만, 그것이 주요 역할은 아닙니다.

3. 예상 사용 사례에서 instructions 작성 — "나중"이 아닌 생성 시점에

instructions는 검색 회수율(recall)에 영향을 주지 않습니다 — 검색 회수율은 벡터 검색과 max_distance에 의해 결정됩니다. 이는 KB의 발췌문 옆에 답변 시점에 삽입되므로, 모델이 검색된 내용을 어떻게 사용하는지를 지배합니다. 비워두면 KB는 여전히 검색하지만, 답변에서 KB 고유 규칙(권위, 경계, 인용 관례)이 모두 손실됩니다. 특별한 규칙이 없는 일반 참고 자료인 경우에만 비워두는 것이 허용됩니다.

KB가 실제로 사용되는 방식에서 유도하십시오 — 질문당 한 줄:

KB 유형별 지식베이스 지침 예시:

# Website-content KB (products, services, team, blog)
instructions="Company website content: products, services, team and blog posts. Authoritative
for what we offer and who we are. Marketing copy is not a contractual promise — for prices,
terms or eligibility prefer the policy KB; if only this KB answers, attribute it to the website."
 
# Policy / regulation KB
instructions="Current company policy, effective 2026; overrides industry norms and prior
knowledge. Covers home mortgages only — for car or personal loans, say so and hand off.
Any quoted rate or fee must state its effective date."
 
# Product-docs KB
instructions="Official product documentation for the current release. State the version when a
feature is version-dependent. If the docs don't cover something, say so — never fill the gap
from general knowledge."

4. 콘텐츠 추가

add_knowledge_text(kb_name="Company policy", title="2026 late-fee rule",
                   content="From 1 July 2026 the daily late fee is 0.019% …")

이진 파일(pdf/docx) 및 전체 폴더(zipped)는 add_knowledge_file을 통해 처리됩니다 — 하위 폴더가 탐색되며, 각 md/txt/pdf/html/docx 파일은 아카이브 내 경로 아래에 가져옵니다.

4b. 검색되기를 원하는 문장 작성

검색은 의미를 일치시키며, 값 자체만으로는 거의 의미가 없습니다. 이는 사용자가 제어할 수 있는 가장 높은 레버리지 요소이며, 오류가 발생하지 않기 때문에 잘못하기 쉽습니다 — 검색은 여전히 무언가를 반환하지만, 올바른 것은 아닙니다.

실제 고객 카탈로그에는 1,500개 기록 중 1,480개에 다음 줄이 있었습니다:

Reading level: 1 · Age: 5 · Words: 1951

그리고 "혼자 읽기 시작하는 어린 아이에게 적합한 책은 무엇인가"라는 질문에 음악 천재에 대한 책이 반환되었습니다. 사실은 텍스트에 있었지만 여전히 도달 불가능했습니다: 1은 한 단어가 다른 단어를 닮은 방식처럼 초보자 독자와 전혀 닮지 않았습니다.

값 옆에 한 문장을 추가하면 해결되었습니다 — 동일한 기록에서 측정됨:

Reading level: 1 · Age: 5
Suitable for around age 5, for children just starting to read on their own.

(낮을수록 더 가깝습니다. 이 모델에서 두 무관한 구절은 약 0.61에 위치하므로, 마지막 행은 "운보다 약간 나은 수준"에서 진정한 일치로 이동합니다 — 그리고 이 이득은 언어 전반에 걸쳐 지속됩니다.)

규칙: 질문이 문장보다는 속성(가격, 날짜, 수준, 가용성, 재고)에 의해 답변된다면, 단어로도 명시하십시오. 구조화된 값은 필터링용입니다. 검색은 쓰여진 것을 찾습니다.

시간을 들일 가치가 없는 것

내보내기는 종종 자신을 반복합니다 — 동일한 문장을 담은 summary와 description. 이는 낭비처럼 보이며, 이것이 벡터를 "소모한다"는 직관은 잘못되었습니다. 우리가 측정해 보니 중복 제거가 검색에 +0.002 거리 변화를 가져왔을 뿐입니다 — 즉, 60개 기록 전체에서 아무것도 아닙니다. 임베딩은 예산이 아닌 방향입니다. 같은 말을 두 번 하는 것은 주로 같은 방향으로 두 번 가리키는 것과 같습니다.

그냥 두십시오. 대신 위의 문장에 노력을 쏟으십시오.

4c. 문서에 공통 헤더가 있는 경우 구조화된 인덱스 구축

벡터 검색은 세지 못하며, 숫자로 필터링하거나 그룹화할 수 없습니다. "몇 개 있습니까", "200 단어 미만인 것은 무엇입니까", "카테고리별 개수는 얼마입니까"는 나쁘게 답변되는 것이 아니라 구조적으로 답변 불가능하며, 에이전트는 거절하거나 우연히 검색된 몇몇 기록에 대해 보고할 것입니다.

build_knowledge_index(name="books", roles=["identity", "link", "image"])

문서가 기계 읽기 가능한 헤더를 공유할 때만 호출할 가치가 있습니다 — 메타데이터 테이블, YAML front matter, Field: value 줄 등. 제품 내보내기, 카탈로그, 리플릿 및 과정 목록은 일반적으로 해당됩니다. 산문은 해당되지 않으며, 값이 모두 다른 테이블을 구축하는 호출은 거부됩니다. 거부는 우회해야 할 오류가 아닌 올바른 결과입니다.

roles는 정확히 추출되어야 하며 절대 재문서화되지 않는 필드를 명명합니다:

사용자에게 이 필드들이 무엇인지 묻습니다. 추론하지 마십시오. 세 URL 중 어느 것이 고객을 보낼 유일한 URL인지는 데이터가 명시하지 않는 비즈니스 사실입니다. 선언된 역할을 찾을 수 없는 경우, roles.unresolved에 후보 필드 이름과 함께 반환됩니다 — 하나를 선택하기보다는 이를 사용자에게 제시하십시오.

dropped를 읽고 사용자에게 알리기

{"built": true, "documents": 4523,
 "columns": ["title", "age", "word_count", "genre", "read_url", "cover_url"],
 "dropped": [["isbn", "not_found", "no anchor 'ISBN: ' in the sample"]]}

삭제된 열은 다른 모든 곳에서 보이지 않습니다: 이후 답변은 단순히 이를 우회하여 작동하므로, 이 보고서는 유일하게 언급되는 곳입니다. get_knowledge_index도 동일하며, 그 경고는 일반적으로 고객이 알지 못했던 데이터 문제를 노출합니다 — 실제 카탈로그 중 하나에서 기록의 10%가 페이지 수 0을 가졌는데, 이는 짧은 책이 아니라 0으로 기록된 누락 값이었으며, 이를 기반으로 구축된 모든 평균을 낮추었을 것입니다.

고객의Own terms로 보고하십시오. 플랫폼의 다른 어디에서도 그렇지 않습니다.

나중에 변경하기

patch_knowledge_index(name="books", request="also track the author", apply=false)

먼저 apply=false로 실행하여 사용자에게 변경 사항을 미리 보여주고, 여러 편집을 배치한 후 한 번에 적용하십시오. 적용 시 저장된 텍스트에서 필드를 다시 읽습니다. 아무것도 다시 임베딩하지 않으므로 비용이 저렴합니다.

문서가 포함하지 않는 것을 요청하면 이유와 함께 refused 항목이 반환됩니다 — 우회책을 발명하는 대신 이를 사용자에게 그대로 전달하십시오.

5. ★ 검색 검증 — 건너뛰지 마세요 ★

search_knowledge_base(kb_name="Company policy", query="how is the late fee calculated")
#   hits  → the agent can answer this
#   empty → the agent will treat it as "not covered" and say so

6. 마운트하기

update_agent(name="Support", add_knowledge_bases=["company-policy"])   # incremental — keeps existing mounts

instructions에 "항상 구절을 인용하십시오"라고 작성하지 마십시오 — 해당 동작은 내장되어 있습니다. 오직 이 라이브러리에 고유한 내용만 작성하십시오: 권위 순서, 범위 경계, 특수 사용 사례(예: "이자율 인용 시 유효 날짜 명시").

보고하십시오 — "가져옴"에서 멈추지 마십시오. 사용자에게 몇 개의 청크가 도착했는지 알려주고 지식베이스와 지식 스타맵(흡수된 내용의 3D 뷰)을 열 수 있는 클릭 가능한 링크를 제공하십시오: https://console.agent4.io/#/knowledge-bases/Company%20policy — 그런 다음 에이전트에 연결되었는지 확인하십시오.