매뉴얼웍스가 제공하는 챗봇은 매뉴얼웍스로 작성한 문서의 내용에서만 답변합니다. 따라서 챗봇이 답변할 때 사용할 문서를 설정해야 합니다.

챗봇 설정

벡터 저장소에 있는 문서 추가

매뉴얼웍스의 챗봇은 설정된 문서 내에서만 답변하도록 제한되어 있습니다.

챗봇이 질문에 답할 때 참고할 문서를 추가합니다. <AI | 벡터 저장소> 메뉴에서 임베딩한 문서만 추가할 수 있습니다. 챗봇을 처음 시작할 때는 사용자에게 참고하는 문서 목록을 보여줍니다.

용어를 다음처럼 이해하면 설정이 쉽습니다. “벡터 저장소”는 챗봇이 검색하는 문서 집합, “문맥”은 검색으로 가져온 텍스트 조각, “RAG”는 검색한 문맥을 이용해 답변을 생성하는 방식입니다.

다음 순서로 챗봇이 참고할 문서를 추가합니다.

<AI | AI 어시스턴트> 메뉴로 이동합니다.
만든 <챗봇> 어시스턴트를 클릭합니다.
벡터 저장소 패널의 <1추가> 링크를 클릭하여 참고할 문서를 선택합니다.
벡터 저장소 문서 목록을 확인합니다.

문서를 임베딩할 때 사용한 2AI 모델이 같은 문서만 추가할 수 있습니다. 임베딩 모델마다 유사도 측정 기준이 다르므로 혼용할 수 없습니다.

한 문서를 여러 임베딩 모델로 벡터화했더라도 동일한 문서라면 챗봇에는 그중 하나만 추가할 수 있습니다.

챗봇이 답변할 때 참고하는 문서가 많을수록 답변 속도는 느려집니다. 이는 매뉴얼웍스를 운영하는 시스템 환경에 따라 달라지므로 정확한 기준은 없으며, 경험적으로 조정해야 합니다. REST API 요청 및 응답을 로그 파일에 기록하도록 설정하면 벡터 검색에 걸린 시간도 함께 기록됩니다.

<3테스트> 링크를 클릭하면 챗봇에 질문했을 때의 벡터 저장소 검색 결과를 확인할 수 있습니다. 결과는 표로 보여 주며, 최종 선택 여부(Final), RRF 적용 전후 순위와 RRF 점수, 벡터 유사도(Vector), Rerank 점수, 단락 아이디와 내용을 함께 표시합니다.

장과 단락을 RAG에서 제외하기

여러 장의 개요를 설명하는 머리말 같은 장을 벡터 저장소에 저장하는 것은 챗봇 답변 품질을 높이는 데 도움이 되지 않습니다. 그래서 이런 장이나 단락을 벡터 저장소에 저장하지 않는 기능을 추가했습니다.

웹, PDF, EPUB 감추기 기능과 동일하게 적용합니다. 장은 장 변경 화면에서, 단락은 에디터 단락 옵션에서 설정할 수 있습니다. RAG에서 제외된 항목은 벡터 저장소 생성 대상에서 자동으로 제외됩니다.

웹 뷰어에서 챗봇을 표시할 문서 선택

“챗봇이 표시되는 문서”를 설정하면 해당 문서의 웹 뷰어 사이드바에 <1챗봇> 아이콘이 생성됩니다. 이 아이콘을 클릭하면 사이드 패널에 2해당 챗봇이 참고하는 문서를 보여줍니다.

다음 순서로 웹 뷰어에서 챗봇을 표시할 문서를 추가합니다.

<AI | AI 어시스턴트> 메뉴로 이동합니다.
만든 <챗봇> 어시스턴트를 클릭합니다.
“챗봇이 표시되는 문서” 패널의 <추가> 링크를 클릭하여 문서를 선택합니다.
챗봇이 표시되는 문서 목록을 확인합니다.

챗봇 공개하기

다른 AI 어시스턴트와 달리 챗봇은 로그인하지 않은 사용자에게도 공개할 수 있습니다.

<AI | AI 어시스턴트> 메뉴로 이동합니다.
AI 어시스턴트 목록에서 공개할 <챗봇>을 선택하여 클릭합니다.
“옵션” 패널에서 <1공개하기> 토글 버튼을 켭니다.

챗봇은 서버가 벡터 저장소에서 검색한 문서 조각만 답변에 사용합니다. 챗봇 화면 밖에서 임의의 문서 내용을 넣어 요청해도 답변에 쓰지 않습니다. “사용하지 않음” 상태의 챗봇은 답하지 않습니다.

챗봇 질문 원문은 로그인한 사용자의 아이디 또는 로그인하지 않은 독자의 방문자 쿠키 값과 함께 AI 사용량 기록에 남습니다. 공개 챗봇을 운영할 때는 이 기록을 개인정보 처리 방침에 반영하고, 보관 기간을 정해 둡니다.

챗봇과 Q&A 채널 연결하기

<AI | AI 어시스턴트> 설정 화면에서 챗봇에 특정 채널을 연결할 수 있습니다.

챗봇에 특정 Q&A 채널을 연결하면 챗봇 답변에 1다음 메시지가 추가됩니다.

챗봇 옵션

옵션 설정에 따라 API 토큰 사용량이 증가할 수 있습니다.

다중 쿼리, HyDE, 적응형 검색을 켜면 검색하기 전에 질문을 검색어로 바꿉니다. 이때 AI 어시스턴트의 이름과 설명을 함께 넘겨 어떤 제품의 문서를 찾는지 알려 줍니다. AI 어시스턴트의 설명에 제품이 무엇인지 한 줄 적어 두면 질문 속 용어를 다른 제품의 뜻으로 읽어 검색이 빗나가는 일을 줄일 수 있습니다.

사용자 프롬프트에 용어 규칙 적용

옵션으로 켜고 끄는 기능이 아니라 늘 적용합니다. 사용자 질문에 <도구 | 용어 규칙> 메뉴에 정의한 대상어가 있으면 그 뒤에 권장어를 괄호로 붙여 대상어(권장어) 형태로 확장한 뒤 검색합니다.

CHATBOT_CONTEXT_SIZE 옵션으로 AI에 전달할 데이터 개수 설정하기

벡터 저장소 검색 결과 중 CHATBOT_CONTEXT_SIZE 옵션에 지정한 개수만큼 AI 모델에 전달합니다. 기본값은 3이며, 변경하려면 콘솔에서 다음 명령어를 실행합니다.

set-preference -name CHATBOT_CONTEXT_SIZE -value 5

유사도가 CHATBOT_MIN_SIMILARITY 옵션 값보다 낮은 검색 결과는 AI 모델에 전달하지 않습니다. 기본값은 0.3입니다.

도구 사용

“도구 사용을 활성화합니다.” 옵션을 설정하면 답변 생성 중 필요한 경우 도구를 호출해 추가 정보를 확인하고, 결과를 바탕으로 답변을 구성합니다. 한 번의 답변에서 도구 호출은 기본값 기준으로 최대 4단계(CHATBOT_MAX_TOOL_CALL_STEPS)까지 이어 갑니다.

현재는 2가지 도구를 제공합니다.

문서 검색(search_documents)

AI가 벡터 저장소 검색으로 전달받은 내용만으로 답변이 어렵다고 판단하면, 스스로 새로운 질문으로 벡터 저장소에서 필요한 자료를 검색합니다. 이때는 다중 쿼리나 HyDE 같은 질문 변환을 다시 하지 않으며, 이번 질문에서 이미 전달한 단락은 빼고 새 단락만 돌려줍니다.

한 번의 답변 생성 과정에서 문서 검색은 기본값 기준으로 최대 총 2회(CHATBOT_MAX_SEARCH_TOOL_CALLS) 실행합니다.

역질문(clarify)

AI가 질문을 한 사용자에게 역질문이 필요하다고 판단될 때 사용하는 도구입니다. 도구 사용 옵션을 켰을 때만 동작합니다. 검색한 문서가 질문이 가리킬 수 있는 서로 다른 주제를 다룰 때, 또는 문서에 답이 없지만 다른 문서에 있을 것 같을 때 선택지를 보여 주며 되묻습니다. 질문이 짧다는 이유만으로는 되묻지 않습니다.

Ollama 제공자의 AI 모델은 도구 호출을 지원하지 않으므로 문서 검색과 역질문 도구를 사용하지 않습니다.

다중 쿼리

“다중 쿼리를 사용합니다.” 옵션을 설정하면 사용자 질문을 여러 검색 질의로 확장하여 다양한 관점의 관련 문맥을 더 넓게 찾습니다. 사용자 질문과 문서 사이에 존재하는 용어 등의 차이로 벡터 저장소 검색 결과가 미흡할 수 있습니다. 이를 개선하기 위해 사용자 질문을 확장해서 벡터 저장소를 검색합니다.

- 사용자 질문
매뉴얼웍스에서 태그를 삭제하는 방법을 알려줘.

- AI로 확장한 질문
매뉴얼웍스에서 태그 삭제 방법
매뉴얼웍스 태그 제거하는 법
매뉴얼웍스 태그 삭제 안내

HyDE(가설 문서 임베딩)

“HyDE(가설 문서 임베딩)를 사용합니다.” 옵션을 선택하면 질문에 대한 가설 문서를 생성해 임베딩 검색 질의에 추가함으로써 관련 문맥 회수율을 높입니다.

Rerank 사용

1차 검색으로 모은 후보 문맥을 질문과의 관련도 기준으로 다시 정렬해 상위 문맥의 정확도를 높입니다.

RRF(Reciprocal Rank Fusion) 사용

서로 다른 순위 결과를 RRF 방식으로 결합해 최종 문맥 순위를 안정적으로 산정합니다. 벡터 검색 순위와 Rerank 순위를 결합하므로 Rerank를 사용하지 않으면 효과가 없습니다.

적응형 검색

질문 유형을 판단해 검색 전략을 자동으로 조정합니다. 예를 들어 키워드형 질문은 단순 검색을, 그 외 질문은 재정렬 중심 검색을 적용합니다. 이 옵션을 켜면 Rerank와 RRF 옵션 설정은 무시합니다. 또 질문 유형을 판단하려고 검색 전에 질의 분석 API를 한 번 더 호출합니다. 다중 쿼리나 HyDE를 함께 켜면 같은 호출에서 처리합니다.

자가 교정

초안 답변을 한 번 더 검토·수정해 정확성, 일관성, 표현 품질을 높입니다.

챗봇 사용하기

대화 유지하기

기본 정책으로 최대 3건까지 이전 대화를 유지합니다. 서버에서도 최근 3건만 사용하며, 이전 질문과 답변은 각각 4,000자까지만 AI 모델에 전달합니다.

프롬프트 창 기능

1키워드 검색: 문서를 대상으로 키워드 검색을 합니다.
2문서 차례 보기: 문서의 차례를 보여줍니다.
3문서 필터하기: 챗봇이 참고하는 문서를 제한합니다.
4대화 초기화: 화면의 대화 목록과 이전 대화 이력을 지우고 새 대화를 시작합니다.

답변에 대한 피드백 기록

사용자가 답변에 대해 1피드백을 남깁니다. 남긴 피드백은 <AI | AI 사용량> 메뉴에서 확인합니다. 피드백은 답변을 받은 사람만 남길 수 있습니다. 로그인한 사용자는 계정으로, 로그인하지 않은 독자는 방문자 쿠키로 확인합니다. 답변을 받은 지 24시간이 지나면 피드백을 남길 수 없습니다.

독립적으로 챗봇 사용하기

웹 뷰어와 관계없이 챗봇을 사용할 수 있습니다. iframe 태그를 이용해 원하는 위치에 챗봇을 넣을 수 있습니다.

<iframe src="http://127.0.0.1:1975/r/chatbot/open/${uuid}"></iframe>

다음을 참고합니다.

http://127.0.0.1:1975를 운영 중인 매뉴얼웍스 주소로 변경합니다.
${uuid}를 챗봇의 아이디로 변경합니다.
챗봇을 시작하는 버튼 등은 매뉴얼웍스와 별도로 직접 구현해야 합니다. 해당 버튼을 클릭했을 때 iframe을 통해 챗봇이 시작되도록 구성합니다.

라이브러리에 챗봇 설정하기

라이브러리에 챗봇을 연결할 수 있습니다. 이때 메인 화면에서 챗봇을 보여줍니다.

<도구 | 라이브러리> 메뉴로 이동합니다.
챗봇을 설정한 라이브러리를 선택합니다.
<라이브러리> 변경 링크를 클릭합니다.
<챗봇>을 선택한 후 버튼을 클릭합니다.

챗봇 이력으로 문서 고치기

챗봇이 답하지 못한 자리는 독자도 막히는 자리입니다. 챗봇은 그 자리를 AI 로그에 남깁니다. AI 도구가 MCP로 이 이력을 읽으면 고쳐야 할 문서를 찾아 태스크로 정리할 수 있습니다.

매뉴얼웍스 6.0.26 버전부터 지원합니다.

네 가지 신호

이력을 처음부터 끝까지 읽지 않고 다음 신호에 걸린 자리만 먼저 봅니다. 모델을 새로 부르지 않고 이미 남은 로그로 셉니다.

신호	뜻
재질문	같은 사람이 얼마 지나지 않아 비슷한 질문을 다시 했습니다. 첫 답이 빗나갔거나 모자랐다는 가장 강한 신호입니다.
문서에 없음	챗봇이 문서에 답이 없다고 말했습니다.
검색 한도 도달	챗봇이 문서를 더 찾으려다 문서 검색 횟수 한도에 막혔습니다.
도움이 되지 않음	독자가 답변에 「도움이 되지 않음」 피드백을 남겼습니다.

MCP로 신호 보기

챗봇 이력을 읽고 챗봇을 시험하는 MCP 도구는 기본으로 꺼져 있습니다. 콘솔에서 다음 명령어로 켭니다.

set-preference -name AI_LOG_MCP_ACCESS -value true

관리 권한이 있는 사용자만 쓸 수 있으며, 다른 사용자에게는 MCP 도구 목록에도 보이지 않습니다. AI 도구를 매뉴얼웍스 MCP에 연결하는 방법은 Claude Code/Codex/Gemini CLI에서 매뉴얼웍스 사용하기를 참고합니다.

신호는 다음 두 도구로 봅니다.

get_chatbot_reasks: 재질문을 찾습니다. 기본으로 24시간 안에 유사도 0.8 이상인 질문을 다시 한 것을 찾습니다. minSimilarity로 유사도 기준을, withinHours로 시간 간격을 바꿀 수 있습니다. withinHours는 최대 168시간입니다. 결과는 한 쪽에 20쌍씩 유사도가 높은 순으로 돌려주며, page는 50까지 받으므로 상위 1,000쌍까지 볼 수 있습니다. 재질문이 이보다 많으면 totalPage는 50이고 truncated가 true입니다. 더 보려면 minSimilarity를 올리거나 기간을 나눠 조회합니다.
get_chatbot_weak_answers: 문서에 없음, 검색 한도 도달, 도움이 되지 않음을 찾습니다. 자가 교정을 켠 챗봇은 교정한 최종 답변을 기준으로 판단합니다.

두 도구 모두 날짜(date)를 반드시 지정합니다. 그날까지 며칠을 볼지는 days로 정하며, 기본값은 1일이고 최대 92일입니다. AI 어시스턴트 화면이나 MCP에서 시험 실행한 세션은 결과에서 빠집니다.

로그인하지 않은 독자는 방문자 쿠키로 같은 사람인지 가립니다. 이 값은 6.0.26 버전부터 로그에 남으므로 그 전 로그에서는 로그인한 사용자의 재질문만 찾습니다.

「인덱스」와 「찾아보기」처럼 뜻은 같아도 글이 전혀 다른 짧은 질문은 재질문으로 잡히지 않을 수 있습니다. 문서에 없음은 답변 문장으로 판단하므로 드물게 다른 답변이 걸리거나 빠질 수 있습니다.

MCP로 세션 읽기

신호에 걸린 자리의 앞뒤 대화는 다음 두 도구로 읽습니다.

get_chatbot_sessions: 지정한 날짜의 챗봇 세션 목록을 봅니다. 피드백과 상태로 거를 수 있으며, 시험 실행 세션은 따로 지정하지 않으면 빠집니다.
get_chatbot_session: 한 세션의 로그를 순서대로 봅니다. 지정한 로그만 요청과 응답 전체를 함께 봅니다. 후보 검색 로그에는 상위 후보 10개가 어느 문서의 어느 단락인지와 유사도, 그 후보를 가져온 검색어를 함께 보여 주므로 본문을 펼치지 않아도 검색이 어디로 갔는지 알 수 있습니다.

MCP로 챗봇 시험하기

문서를 고친 뒤 챗봇이 제대로 답하는지 다음 두 도구로 확인합니다.

test_chatbot: 챗봇에 질문 하나를 보내 답변, 사용한 단락, 모델 호출 수를 봅니다. 실제 AI 모델을 호출하므로 비용이 듭니다.
test_chatbot_retrieval: 답변은 만들지 않고 검색 단계만 실행해 후보 단락과 점수, 순위를 봅니다.

두 시험 도구는 합쳐서 하루에 CHATBOT_TEST_DAILY_LIMIT 옵션 값만큼만 호출할 수 있습니다. 기본값은 50회입니다. 호출 수는 서버 노드마다 따로 세고, 서버를 다시 시작하면 처음부터 다시 셉니다.

AI 도구에게 맡기기

AI 도구에게 다음처럼 요청합니다.

지난 일주일 챗봇 이력에서 재질문과 답이 시원찮았던 자리를 찾아줘. 걸린 세션을 읽고 문서에서 고칠 곳을 태스크 초안으로 정리해줘.

AI 도구가 문서를 바로 고치게 하지 않고 태스크 초안을 만들게 합니다. 사람이 검토하고 태스크를 닫습니다.

고칠지는 사람 독자를 기준으로 정하기

신호는 어디를 볼지 알려줄 뿐입니다. 고칠지 말지는 사람 독자를 기준으로 정합니다. 챗봇이 찾기 쉽게만 고치면 문서가 사람이 아니라 검색기에 맞춰집니다.

사람에게는 필요하지만 챗봇 답변을 방해하는 장이나 단락은 지우지 않고 RAG에서 제외합니다.