벡터 저장소

매뉴얼웍스는 AI 제공자의 임베딩 모델을 API로 호출하여 매뉴얼웍스로 작성한 문서를 벡터화해 저장합니다. 챗봇을 사용하려면 문서를 임베딩하여 벡터 저장소(매뉴얼웍스의 내부 모듈)에 저장해야 합니다.

<AI | 벡터 저장소> 메뉴는 “관리” 권한이 있는 사용자만 사용할 수 있습니다.

벡터 저장소(Vector Store)란?

벡터 저장소는 텍스트, 이미지, 오디오 같은 비정형 데이터를 벡터로 변환해 저장하고, 유사도 검색을 통해 의미적으로 비슷한 데이터를 찾아주는 특수한 데이터베이스입니다. AI 기반 검색 시스템, 추천 엔진, RAG(Retrieval-Augmented Generation, 검색 증강 생성) 애플리케이션 등에 활용됩니다.

매뉴얼웍스의 챗봇은 벡터 저장소를 이용한 RAG를 지원합니다.

문서 임베딩 및 저장하기

AI 어시스턴트를 사용할 때와 마찬가지로 문서를 임베딩할 때도 비용이 발생합니다. 자세한 내용은 사용하는 AI 제공자의 문서를 참고합니다.

다음 순서로 문서를 임베딩하고 그 결과를 벡터 저장소에 저장합니다.

  1. <AI | 벡터 저장소> 메뉴로 이동합니다.

  2. <문서 추가> 링크를 클릭하여 임베딩할 문서를 선택합니다.

    • 임베딩용 AI 모델이 하나도 없으면 문서를 선택하기 전에 “임베딩 모델이 없습니다. 먼저 AI 제공자에서 임베딩 모델을 AI 모델로 추가하세요.”라는 메시지가 나옵니다.

  3. ‘임베딩용 AI 모델’을 선택하고 <문서 임베딩 및 저장> 링크를 클릭합니다.

    • AI 제공자에서 설정한 임베딩용 AI 모델 중에서 선택할 수 있습니다.

  4. 임베딩한 문서가 벡터 저장소 목록에 추가됩니다.

같은 문서를 같은 임베딩용 AI 모델로 다시 추가할 수 없습니다. 바뀐 내용을 반영하려면 임베딩 동기화를 실행합니다. 벡터 저장소 파일은 문서와 AI 모델 이름으로 정한 폴더에 저장하므로, 제공자가 달라도 AI 모델 이름이 같으면 같은 문서에 추가할 수 없습니다. 이때 AI 모델 이름의 콜론(:)은 하이픈(-)으로 바꿔 비교합니다. 예를 들어 bge-m3:latest와 bge-m3-latest는 같은 이름으로 봅니다.

임베딩 API가 오류를 돌려주거나 빈 임베딩을 돌려주면 문서 임베딩과 임베딩 동기화는 실패로 끝납니다. 실패한 호출은 AI 사용량에 오류로 남습니다.

임베딩용 AI 모델이 필요합니다. 매뉴얼웍스가 지원하는 AI 제공자 중 Claude, Grok, OpenRouter는 임베딩용 AI 모델을 지원하지 않습니다. Gemini, OpenAI, Ollama, Voyage AI는 임베딩용 AI 모델을 지원합니다.

문서 변경 사항 벡터 저장소에 반영하기

임베딩한 문서의 내용이 바뀌면 그 변경 사항을 벡터 저장소에 반영해야 챗봇이 최신 내용으로 답합니다. 직접 반영하거나 자동 업데이트를 켜 둡니다. 직접 반영하는 순서는 다음과 같습니다.

  1. <AI | 벡터 저장소> 메뉴로 이동합니다.

  2. 목록에서 변경 사항을 반영할 문서의 <임베딩 동기화> 링크를 클릭합니다.

  3. 슬라이딩 패널의 버튼을 클릭하면 벡터 저장소에 변경 사항을 반영합니다.

<이력 비교> 링크를 클릭하면 문서를 임베딩(또는 임베딩 동기화)한 뒤 바뀐 내용을 확인할 수 있습니다.

같은 벡터 저장소는 한 번에 하나만 동기화합니다. 동기화가 끝나기 전에 다시 누르면 “이 벡터 저장소를 이미 동기화하고 있습니다. 끝난 뒤에 다시 시도하세요.”라는 메시지가 나옵니다. 직접 동기화하는 중에 자동 업데이트 차례가 오면 그 벡터 저장소는 건너뛰고 다음 주기에 업데이트합니다.

자동 업데이트

<AI | 벡터 저장소> 메뉴의 목록에서 벡터 저장소의 “자동 업데이트”를 켜면 7일마다 벡터 저장소를 다시 만듭니다. 문서를 자주 고칠 때 임베딩 동기화를 직접 실행하지 않아도 됩니다.

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

저장된 문서 삭제하기

임베딩하여 벡터 저장소에 저장한 문서는 삭제할 수 있습니다.

  1. <AI | 벡터 저장소> 메뉴로 이동합니다.

  2. 삭제할 문서의 <삭제> 링크를 클릭합니다.

  3. 벡터 저장소 문서 목록에서 해당 문서가 삭제됩니다.

AI 어시스턴트에 추가한 벡터 저장소는 삭제할 수 없습니다. “이 벡터 저장소를 쓰는 AI 어시스턴트가 있어 삭제할 수 없습니다. 먼저 AI 어시스턴트에서 빼세요.”라는 메시지가 나오면 AI 어시스턴트의 벡터 저장소 패널에서 해당 문서를 먼저 삭제합니다. 예전 버전에서 같은 문서를 이름이 같은 AI 모델로 두 번 추가했다면 두 벡터 저장소가 파일을 함께 씁니다. 이 가운데 하나를 삭제하면 목록에서만 빼고, 남은 벡터 저장소가 쓰는 파일은 지우지 않습니다.

삭제 후 문서를 다시 임베딩할 경우 비용이 발생하므로, 삭제 시 주의가 필요합니다.

임베딩 대상 문서 내용

문서 공개와 임베딩

한 문서를 여러 AI 모델로 임베딩할 수 있습니다. 다만 임베딩 대상이 되는 문서 내용은 최신 내용 또는 공개한 태그의 내용만 사용합니다. 따라서 태그별로 문서를 따로 임베딩할 수는 없고, 공개한 태그가 있으면 그 내용을 임베딩합니다. 공개한 태그가 없으면 최신 내용을 임베딩합니다. 이는 문서를 임베딩(또는 임베딩 동기화)하는 시점을 기준으로 결정합니다.

웹 뷰어 기준

웹 뷰어에 표시되는 문서를 기준으로 임베딩합니다. 웹 뷰어에서 숨겨진 장과 숨겨진 단락(교정 단락)은 임베딩하지 않습니다. 반면 참조한 장이나 다른 단락 가져오기로 포함한 단락은 임베딩합니다.

RAG에서 제외한 장과 단락

RAG에서 제외하도록 설정한 장과 단락은 임베딩하지 않습니다.

참조 단락만 있는 부분

매뉴얼웍스 6.0.26 버전부터는 제목 말고는 다른 곳을 가리키는 참조 단락만 있는 부분을 임베딩하지 않습니다. 담긴 정보가 없는데 제목과 링크 글자 때문에 검색 결과 상위를 차지하기 때문입니다. 가리키는 곳의 내용은 따로 임베딩합니다. 이 버전 전에 만든 벡터 저장소에는 임베딩 동기화를 실행하거나 자동 업데이트가 한 번 돌아야 반영됩니다.

참조 단락은 문서 안 링크가 있는 보통 단락 가운데, 링크를 뺀 나머지 글이 없거나 “…를 참고합니다.”처럼 “참고”, “참조”, “see”, “refer” 같은 안내 말이 든 50자 이하의 한 문장인 단락입니다. 이보다 길거나 문장이 둘 이상이면 참조 단락으로 보지 않고 임베딩합니다.

EMBEDDING_MAX_INPUT_LENGTH 옵션으로 임베딩 입력 길이 설정

큰 표나 긴 코드 블록이 있으면 한 번에 임베딩할 내용이 임베딩용 AI 모델의 입력 한도를 넘을 수 있습니다. 예를 들어 OpenAI의 임베딩 모델은 8192토큰을 넘는 입력을 거부하고, 이때 문서 임베딩이 실패합니다. 그래서 매뉴얼웍스는 임베딩 API에 보내는 내용을 최대 6000자까지만 보냅니다. 잘라 내는 것은 임베딩할 때뿐이고, 챗봇이 답변할 때는 그 부분의 내용을 모두 사용합니다.

입력 한도가 더 작은 임베딩용 AI 모델을 사용하면 이 값을 줄입니다. 0으로 정하면 자르지 않습니다. 이 값을 변경하려면 콘솔에서 다음 명령어를 실행합니다.

set-preference -name EMBEDDING_MAX_INPUT_LENGTH -value 2000

매뉴얼웍스 6.0.27 버전(빌드 번호 1106)부터 지원합니다.

VECTOR_STORE_CACHE_SIZE 옵션으로 자바 힙 메모리 캐시 크기 설정

유사도 검색 성능을 높이기 위해 자바 힙 메모리에 임베딩한 문서를 최대 10개까지 캐시합니다. 이 수를 변경하려면 콘솔에서 다음 명령어를 실행합니다.

set-preference -name VECTOR_STORE_CACHE_SIZE -value 5