의미 검색과 전문 검색

한 줄로: semantic_search와 search_content가 어떻게 다른지, 그리고 어떤 질문을 어느 도구에 던져야 하는지 정리했습니다.

이 글이 해결하는 문제

MCP에서 무언가를 찾는 방법은 하나가 아니고, 각각 다른 질문에 답합니다.

search_content는 직접 타이핑한 글자를 찾습니다. 「글자 용광로」라고 썼던 기억이 있다면, 그 표현이 나온 자리를 경로와 앞뒤 문장까지 붙여 전부 늘어놓습니다.

semantic_search는 말하려던 그것을 찾습니다. "어머니의 원망이 처음 드러나는 장면은 어디인가"라고 물으면, 그 단락에 '어머니'도 '원망'도 한 번 안 나와도 그 장면을 돌려줍니다.

장편을 쓰다 보면 실제로 떠오르는 질문은 대부분 뒤쪽입니다. 그런 대목이 있었다는 건 기억나는데, 그때 무슨 단어를 썼는지는 기억나지 않습니다.

어느 쪽을 쓸 것인가

하고 싶은 일	쓸 도구
「승문 해역」이라는 말이 들어간 파일 전부 찾기	search_content
인물 이름을 바꾸기 전에 그를 언급한 자리 전부 찾기	search_content
두 사람의 관계가 틀어지기 시작하는 장면 찾기	semantic_search
해금령의 내력을 작품 어딘가에서 이미 설명했는지 확인	semantic_search
고쳐 쓰기 전에 썼던, 밀물이 글자를 씻어 간다는 비유 찾기	semantic_search
팀 지식 베이스에 이런 상황을 다룬 규정이 있는지 확인	semantic_search

search_content: 글자 그대로 대조

search_content({
  "book_token": "bk_...",
  "query": "글자 용광로",
  "file_types": ["md"],
  "limit": 20
})

대소문자를 구분하지 않으며, 걸린 파일의 경로와 그 앞뒤 몇 줄을 돌려줍니다.

4.0 작품에서는 file_types 인자가 보기보다 중요합니다. 구조화 파일(.beats, .timeline, .script, .map, .geomap)도 검색 대상에 들어가는데, 검색되는 것은 그 원본 JSON입니다. 그래서 name이나 title 같은 흔한 단어를 찾으면 내용이 아니라 필드 이름만 한 페이지 나올 수 있습니다. 산문만 보고 싶다면 file_types: ["md"]라고 명시하십시오.

예전 시나리오 스튜디오 작품은 반대입니다. 그쪽에서는 구조화 파일이 기본적으로 제외되며, 함께 검색하려면 include_structured: true를 붙여야 합니다. 특정 파일에서 다르게 동작하는 도구들에 자세히 적어 두었습니다.

semantic_search: 의미로 찾기

semantic_search({
  "book_token": "bk_...",
  "query": "심연이 아버지를 처음 의심하는 대목",
  "limit": 10
})

인자는 셋입니다. 작품, 자연어로 쓴 질문, 그리고 결과 개수(기본 10, 최대 50).

결과 한 건에는 네 가지가 담겨 옵니다. 단락의 §번호, 파일 토큰, 그 단락의 본문, 그리고 유사도 점수입니다. §번호는 인용할 수 있는 위치 표시입니다. AI가 "책 중간쯤"이라고 얼버무리는 대신 "3장 §4에 있습니다"라고 답할 수 있습니다.

색인은 어디서 오는가

첫 검색 때 Slima는 그 작품의 가장 최근 커밋 내용을 단락 단위로 잘라 색인합니다. 그 뒤로는 바뀐 부분만 다시 계산하므로, 손대지 않은 파일에는 비용이 들지 않습니다. 그래서 큰 작품은 첫 검색이 그다음 검색들보다 느립니다.

분량이 크고 한 번도 색인된 적 없는 작품은 백그라운드 작업으로 넘어갑니다. 그 검색은 빈 결과로 돌아옵니다. "일치하는 것이 없다"가 아니라 "아직 만들어지지 않았다"입니다. 잠시 뒤 다시 검색하면 결과가 나옵니다.

비용이 조금 듭니다

질문을 벡터로 바꾸는 계산이 한 번 들어가므로 semantic_search는 크레딧을 조금 씁니다. 글자 검색은 쓰지 않습니다. 액수는 작지만 두 도구 사이의 유일한 비용 차이라 알아 둘 만합니다.

하지 못하는 세 가지

• 정확한 문자열 찾기. 특정 단어나 문장 부호를 정확히 찾아야 한다면 search_content를 쓰십시오.
• 아직 커밋되지 않은 글 찾기. 색인은 커밋에서 만들어집니다. 작가가 방금 앱에서 타이핑하고 아직 커밋되지 않은 단락은 여기에 없습니다.
• 팀에서 기밀로 설정한 스킬 파일 읽기. 그 파일들은 애초에 색인되지 않습니다. 의미 유사도가 뒷문이 되는 일은 없습니다.

진가가 드러나는 곳: 팀 지식 베이스

팀 지식 베이스 하나에는 집필 규정, 확정된 결정, 전작 설정이 수십 건씩 쌓입니다. 거기서 글자 검색과 의미 검색의 차이는 뒤지기와 물어보기의 차이입니다. 그게 어느 파일에 어떤 제목으로 적혔는지 먼저 알 필요가 없습니다. "이 세계의 화폐 단위를 정해 둔 적이 있나"라고 묻는 것으로 충분합니다.

관련 문서

• Docs: 파일 조작 도구
• Docs: 메모와 코멘트 도구
• Docs: 특정 파일에서 다르게 동작하는 도구들
• Docs: 검색과 바꾸기