Skip to main content

벡터 저장소

문서를 의미 기반으로 색인하고, 질의와 관련된 문서를 검색합니다.

설명​

벡터 저장소 노드는 텍스트를 의미 단위로 색인해 두고, 질의와 뜻이 가까운 문서를 찾아 줍니다. 단어가 정확히 일치하지 않아도 의미가 비슷하면 찾아내기 때문에, 문서 검색이나 RAG 챗봇의 근거 자료를 모으는 데 씁니다.

무엇이 들어왔는지에 따라 동작이 결정됩니다. 문서만 들어오면 색인만 하고, 질의만 있으면 검색만 합니다. 둘 다 있으면 색인한 뒤 곧바로 검색합니다. 질의는 query 포트뿐 아니라 질의 속성에 직접 입력한 값도 포함하므로, documents 포트만 연결했더라도 질의 속성에 값이 있으면 색인 후 검색까지 진행됩니다. 노드 카드가 현재 어떤 동작인지 색인 (문서 적재) · 검색 · 색인 + 검색 으로 보여 줍니다.

데이터 저장소 노드와 화면이 비슷하지만 동작은 다릅니다. 검색이 값 일치가 아니라 의미 기반이고, 색인할 때마다 버전이 쌓이며, 한 번 정한 색인 설정은 그 버전에 잠깁니다. 필터도 아무 열에나 걸 수 있는 것이 아니라 색인할 때 미리 고른 열에만 걸립니다.

포트 구성​

입력 포트​

  • documents (선택사항): 색인할 문서가 담긴 데이터셋
  • query (선택사항): 질의가 담긴 데이터셋. 질의로 쓸 열 을 골랐으면 그 열의 마지막 행을 질의로 쓰고, 고르지 않았으면 대화 이력 형태(role/content)에서 마지막 사용자 발화를, 그 외에는 마지막 행에서 값이 있는 첫 열을 씁니다. 여기서 질의를 얻지 못하면 질의 속성 값으로 넘어갑니다. 검색 조건으로 쓸 열 을 골랐으면 같은 마지막 행에서 검색 조건도 읽습니다

출력 포트​

  • 데이터셋: 검색을 했다면 검색 결과, 색인만 했다면 색인 요약

검색 결과에는 찾은 본문(chunk_content), 원본 행의 나머지 열, 유사도(relevance)가 담깁니다. 원본 열 이름이 chunk_content 나 relevance 와 겹치면 그 열에 _src 를 붙여 구분합니다. 색인만 한 경우에는 인덱스 이름, 버전, 이번 실행에서 색인한 문서·청크 수, 버전 전체의 문서·청크 수가 한 행으로 나옵니다.

속성​

검색 결과 수 (Top K)​

검색으로 가져올 문서 수입니다. 기본값은 3입니다.

질의로 쓸 열​

query 포트로 들어온 데이터셋에서 질의로 쓸 열을 고릅니다. 고른 열의 마지막 행 값이 질의가 됩니다.

비워 두면 자동으로 정합니다. 데이터셋이 대화 이력 형태(role/content 열)면 마지막 사용자 발화를, 그 외에는 마지막 행에서 값이 있는 첫 열을 씁니다. 질의 열이 첫 번째가 아닌 데이터셋에서는 id 나 시각 같은 다른 열이 질의로 잡힐 수 있으니, 그런 경우에는 열을 직접 고르세요.

검색 조건으로 쓸 열​

query 포트로 들어온 데이터셋에서 검색 조건 목록이 담긴 열을 고릅니다. 고른 열의 마지막 행 값을 검색 조건으로 씁니다. 워크플로우 API 를 호출할 때마다 검색 조건을 바꾸고 싶을 때 씁니다. 조건 목록을 쓰는 방법은 API로 검색 조건 넘기기 를 참고하세요.

이 열에 조건이 들어오면 설정 창의 검색 조건 은 쓰지 않고 들어온 조건만으로 검색합니다. 두 조건을 합치지 않습니다. 설정 창의 검색 조건 은 이 열이 없거나 값이 비어 있을 때만 쓰는 기본값입니다.

조건 열의 값검색에 쓰는 조건
열을 고르지 않음설정 창의 검색 조건
데이터셋에 그 열이 없음설정 창의 검색 조건
값이 비어 있음 (빈 칸, null)설정 창의 검색 조건
빈 목록 []조건 없이 검색
조건 목록들어온 조건만 (여러 개면 모두 만족하는 문서만)
형식이 틀림노드가 오류로 멈춤

질의 (query 포트 미연결 시)​

query 포트를 연결하지 않았을 때 사용할 질의를 직접 입력합니다. 포트가 연결되어 있으면 포트 값이 우선합니다.

설정하기​

나머지 설정은 노드 본문의 설정하기 버튼을 눌러 벡터 저장소 설정 창에서 지정합니다. 왼쪽에는 인덱스·임베딩 모델·적재된 문서가, 오른쪽에는 색인 과 검색 설정이 있습니다.

인덱스​

문서를 담아 둘 공간입니다. 목록에서 기존 인덱스를 고르거나, 새 인덱스(＋) 버튼으로 새 이름을 입력해 만듭니다. 새 인덱스는 이름만 정해 두고 첫 색인 때 실제로 만들어집니다.

  • 인덱스 검색: 검색창에 이름을 입력해 목록을 좁힙니다
  • 선택 취소: 고른 인덱스를 해제합니다
  • 새 인덱스: 새 이름을 입력합니다. 이미 있는 이름을 입력하면 경고가 표시되고 만들어지지 않습니다
  • 새로고침: 목록을 최신 상태로 갱신합니다
  • 인덱스 삭제: 인덱스를 지웁니다

목록에는 인덱스마다 활성 버전과 적재량이 v2 · 12문서 · 48청크 형태로 표시됩니다.

임베딩 모델​

텍스트를 벡터로 바꿀 모델입니다. 새 인덱스를 만들 때 고르며, 인덱스를 만든 뒤에는 바꿀 수 없습니다. 기존 인덱스를 고르면 인덱스에 고정 표시와 함께 잠깁니다.

  • qwen3-embedding
  • text-embedding-3-small

적재된 문서​

고른 인덱스의 검색할 버전에 어떤 문서가 들어 있는지, 문서마다 청크가 몇 개인지 보여 줍니다.

색인​

색인 섹션 맨 위에서 실행할 때 문서를 어떻게 넣을지 고릅니다.

  • 기존 버전에 추가: 새 문서만 현재 버전에 더합니다. 이미 색인된 것과 같은 내용은 다시 임베딩하지 않고 건너뜁니다. 이번 입력에 없는 문서는 그대로 남습니다
  • 새 버전으로 다시 색인: 이번 입력이 곧 새 버전이 됩니다. 새 버전으로 전환되고, 이번 입력에 없는 문서는 새 버전에서 빠집니다. 이때도 내용이 같은 청크는 다시 임베딩하지 않고 그대로 씁니다

아직 한 번도 색인하지 않은 인덱스는 어느 쪽을 골라도 첫 실행에서 v1 이 만들어집니다.

색인할 본문 열​

의미 색인의 대상이 되는 열입니다. 이 열의 내용만 검색에 걸리고, 나머지 열은 검색 결과에 함께 따라옵니다.

청크 크기 · 오버랩​

긴 글을 잘라 색인하는 단위입니다. 기본값은 크기 1000, 오버랩 200입니다. 오버랩은 앞 조각의 끝부분을 다음 조각에 겹쳐 넣어, 문장이 조각 경계에서 잘려 문맥을 잃는 것을 줄입니다.

오버랩은 청크 크기보다 작아야 합니다. 크거나 같으면 설정 창에서 경고가 뜨고 적용하기 가 잠깁니다. 이 값이 그대로 실행까지 가면 노드가 오류로 멈춥니다.

필터로 쓸 열​

검색할 때 조건으로 쓸 열을 미리 고릅니다. 열 타입(날짜 / 숫자 / 문자)은 색인할 때 자동으로 판정됩니다.

타입마다 고를 수 있는 개수가 정해져 있습니다 — 문자 10개, 날짜 5개, 숫자 5개, 참거짓 2개입니다. 넘기면 색인이 오류로 멈춥니다. 색인할 본문 열 로 고른 열은 여기에 함께 고를 수 없습니다.

검색할 버전​

검색할 버전을 고릅니다.

  • 최신: 항상 현재 활성 버전을 검색합니다
  • v1 · 48청크 처럼 버전과 청크 수가 함께 나오는 항목: 고른 버전의 스냅샷에 고정합니다

검색 조건​

필터로 쓸 열 에서 고른 열에 조건을 겁니다. 조건을 여러 개 걸면 모두 만족하는 문서만 검색합니다.

열 타입에 따라 쓸 수 있는 조건이 다릅니다.

  • 문자: 같음 · 같지 않음 · 포함됨 · 글자 포함
  • 숫자: 같음 · 같지 않음 · 초과 · 이상 · 미만 · 이하
  • 날짜: 날짜 이상 · 날짜 이하 · 날짜/시간 이상 · 날짜/시간 이하 · 상대 날짜 선택
  • 참거짓: 같음

날짜는 워크플로우가 실행되는 서버의 현지 시각으로 비교합니다. AI Canvas 클라우드 서버는 한국 시각을 씁니다. 시간대가 없는 값(2026-10-06, 2026-10-06 09:00)은 그 현지 시각으로 봅니다. 시간대가 붙은 값(2026-10-06T09:00:00Z, 2026-10-06T18:00:00+09:00)은 현지 시각으로 바꿔 비교합니다. 색인한 날짜도 같은 기준으로 저장하므로 오늘·최근 N시간 같은 상대 날짜 조건도 현지 시각으로 걸립니다.

검색 조건으로 쓸 열 을 골랐다면 여기서 건 조건은 기본값입니다. 그 열에 조건이 들어오면 여기 조건 대신 들어온 조건으로 검색합니다. 이때 이 영역에도 같은 안내가 표시됩니다.

사용 방법​

문서 색인하기​

  1. 벡터 저장소 노드를 캔버스에 추가합니다
  2. documents 포트에 색인할 문서 데이터셋을 연결합니다
  3. 설정하기 버튼을 눌러 설정 창을 엽니다
  4. 새 인덱스(＋) 버튼으로 이름을 입력하거나 목록에서 기존 인덱스를 고릅니다
  5. 색인할 본문 열 에서 의미 색인의 대상이 될 열을 고릅니다
  6. 필요하면 임베딩 모델, 청크 크기, 오버랩 을 조정합니다
  7. 검색할 때 조건으로 쓸 열이 있으면 필터로 쓸 열 에서 고릅니다
  8. 적용하기 를 누른 뒤 노드를 실행합니다

검색하기​

  1. 벡터 저장소 노드를 캔버스에 추가합니다
  2. query 포트에 질의 데이터셋을 연결하거나, 질의 속성에 질의를 직접 입력합니다
  3. query 포트를 연결했다면 질의로 쓸 열 에서 질의가 담긴 열을 고릅니다
  4. 설정하기 버튼을 눌러 검색할 인덱스를 고릅니다
  5. 검색할 버전 을 최신 또는 특정 버전으로 지정합니다
  6. 조건이 필요하면 검색 조건 에서 열·조건·값을 추가합니다
  7. 적용하기 를 누른 뒤 검색 결과 수 (Top K) 를 지정하고 노드를 실행합니다

API로 검색 조건 넘기기​

워크플로우 API 를 호출할 때마다 검색 조건을 바꿔야 할 때 씁니다. 캔버스를 열지 않고 요청 본문만으로 조건을 정할 수 있습니다.

  1. API 데이터 노드의 요청 데이터(JSON 형식) 에 질의 열과 조건 열을 넣고 실행합니다. 예: {"query": "환불 규정", "filters": ""}
  2. API 데이터 노드를 벡터 저장소 노드의 query 포트에 연결하고 벡터 저장소 노드를 워크플로우 API 배포 노드에 연결합니다
  3. 벡터 저장소 노드의 질의로 쓸 열 에서 query 를 고르고 검색 조건으로 쓸 열 에서 filters 를 고릅니다
  4. 설정하기 에서 검색할 인덱스를 고릅니다. 조건이 오지 않을 때 쓸 기본 조건이 있으면 검색 조건 에 함께 추가합니다
  5. 워크플로우를 배포한 뒤 요청 본문의 filters 에 조건 목록을 넣어 호출합니다

아래는 부서가 영업이고 작성일이 2026년 1월 1일 이후인 문서에서 찾는 요청 본문입니다.

{
  "query": "환불 규정",
  "filters": "[{\"col\": \"부서\", \"op\": \"is\", \"val\": \"영업\"}, {\"col\": \"작성일\", \"op\": \"daygte\", \"val\": \"2026-01-01\"}]"
}

조건 목록은 위처럼 문자열로 감싸서 보냅니다. API 데이터 노드는 요청 본문의 배열을 원소마다 한 행으로 펼칩니다. 그래서 filters 에 조건이 두 개 이상인 배열을 그대로 넣으면 query 와 행 수가 맞지 않아 실행이 실패합니다. 본문에 filters 말고 다른 키가 없으면 실패하지 않고 마지막 조건 하나만 적용됩니다. 요청 데이터(JSON 형식) 에 넣는 예시도 같은 이유로 문자열로 적습니다. 조건 없이 검색하려면 빈 목록도 "filters": "[]" 처럼 문자열로 보냅니다.

조건 형식​

조건 하나는 col(열 이름), op(조건), val(값)으로 이루어집니다. col 에는 색인할 때 필터로 쓸 열 로 고른 열만 쓸 수 있습니다. 조건을 여러 개 넣으면 모두 만족하는 문서만 검색합니다.

열 타입op화면 이름val
문자is · not같음 · 같지 않음문자열
문자in포함됨문자열 배열 (["영업", "개발"])
문자contains글자 포함문자열
숫자is · not · gt · gte · lt · lte같음 · 같지 않음 · 초과 · 이상 · 미만 · 이하숫자
날짜daygte · daylte날짜 이상 · 날짜 이하날짜 (2026-01-01)
날짜dategte · datelte날짜/시간 이상 · 날짜/시간 이하날짜와 시각 (2026-01-01 09:00)
날짜relativeDate상대 날짜 선택기간 (아래 참고)
참거짓is · not같음 (not 은 화면에 없고 API 로만 씁니다)true · false

relativeDate 는 실행 시점을 기준으로 한 최근 기간입니다. {"col": "작성일", "op": "relativeDate", "val": "7"} 은 최근 7일입니다. relativeUnit 에 hour 나 year 를 넣으면 시간이나 연 단위가 됩니다. today 를 넣으면 val 없이 오늘 하루를 검색합니다. 날짜를 비교하는 기준은 설정 창의 검색 조건 과 같습니다.

조건 형식이 틀리면 노드가 오류로 멈추고 몇 번째 조건이 왜 틀렸는지 알려 줍니다. 필터로 쓸 열 로 고르지 않은 열을 쓰거나 열 타입에 맞지 않는 조건을 넣어도 오류가 납니다. 값이 빈 in 조건({"col": "부서", "op": "in", "val": []})도 오류입니다. 조건 없이 검색하려면 빈 목록 [] 을 보냅니다.

색인한 뒤 바로 검색하기​

documents 포트를 연결한 상태에서 질의까지 있으면 색인을 마친 뒤 검색합니다. 매번 최신 문서를 반영해 답해야 하는 챗봇 흐름에 씁니다. 이때 검색할 버전 은 최신 으로 두어야 방금 색인한 문서가 검색 대상에 들어옵니다.

문서를 추가하기​

색인 섹션에서 기존 버전에 추가 를 고르고 실행하면 기존 버전에 새 문서만 추가됩니다. 이미 색인된 것과 같은 내용은 다시 임베딩하지 않고 건너뜁니다.

주의사항​

인덱스 삭제는 되돌릴 수 없습니다

인덱스를 삭제하면 색인된 문서와 모든 버전의 청크가 함께 지워집니다. 복구할 수 없습니다.

임베딩 모델은 인덱스 단위로 잠깁니다

한 번 색인한 인덱스는 그때 사용한 임베딩 모델을 계속 따릅니다. 새 버전으로 다시 색인 으로도 바뀌지 않습니다. 다른 모델을 쓰려면 새 인덱스를 만들어야 합니다.

색인 설정은 버전 단위로 잠깁니다

색인할 본문 열, 청크 크기, 오버랩, 필터로 쓸 열 은 버전에 고정됩니다. 기존 버전에 문서를 추가할 때는 그 버전의 설정을 그대로 따르며, 설정 창에서 값을 바꿔도 반영되지 않습니다. 바꾸려면 새 버전으로 다시 색인 을 골라 새 버전을 만들어야 합니다.

검색 조건은 미리 고른 열에만 걸립니다

검색할 버전에서 필터로 쓸 열 로 지정되지 않은 열은 조건으로 쓸 수 없습니다. 필요한 열이 없다면 그 열을 골라 다시 색인해야 합니다.

검색할 버전 고정의 의미

최신 으로 두면 새로 색인할 때마다 검색 대상이 함께 바뀝니다. 배포한 워크플로우가 항상 같은 시점의 문서를 봐야 한다면 특정 버전으로 고정하세요.

색인과 검색을 한 번에 할 때

방금 넣은 문서를 그 실행에서 바로 찾으려면 검색할 버전 이 최신 이어야 합니다. 특정 버전으로 고정해 두면 검색은 그 버전만 보므로, 새로 색인한 문서가 결과에 나오지 않습니다.

검색 조건으로 쓸 열을 고르면 설정 창의 조건은 기본값이 됩니다

호출하는 쪽이 조건 열에 다른 조건이나 빈 목록 [] 을 넣으면 설정 창의 검색 조건 은 쓰이지 않습니다. 특정 문서만 보여 줘야 하는 접근 제어 용도로 설정 창의 조건을 쓰지 마세요.

MCP 서버로 노출할 때

MCP 도구 노드는 API 데이터 노드의 요청 데이터 키마다 배열 인자를 만들고 모두 필수로 둡니다. filters 에는 조건 목록 문자열 하나를 담은 원소 1개짜리 배열을 넘깁니다. 예: "filters": ["[{\"col\": \"부서\", \"op\": \"is\", \"val\": \"영업\"}]"]. 조건마다 원소를 나누면 query 와 원소 수가 달라 실행이 실패합니다. 설정 창의 검색 조건 을 그대로 쓰려면 [""], 조건 없이 검색하려면 ["[]"] 을 넘깁니다.