~/tools / 임베딩과 검색(RAG) / RAG Text Chunker

RAG Text Chunker — RAG용으로 텍스트를 청크로 나누고 Ollama /api/embed 요청 만들기

RAG나 시맨틱 검색을 위해 임베딩하기 전에, 긴 문서를 최대 길이와 겹침(오버랩)을 정해 청크로 나눕니다. 텍스트는 먼저 문단에서, 그다음 줄, 문장, 공백 순서로 자르고, 다른 방법이 없을 때만 단어 중간에서 자릅니다. 청크 목록과 함께, 모든 청크를 요청 하나에 담은 Ollama /api/embed용 curl 명령을 바로 실행할 수 있는 형태로 얻습니다. 데이터는 브라우저 밖으로 나가지 않습니다.

길이는 글자 수입니다. 모델의 컨텍스트 윈도우는 토큰 단위이고 텍스트가 몇 토큰이 되는지는 모델에 따라 다르므로, 여유를 두세요.

curl 명령

Ollama에 접근할 수 있는 컴퓨터에서 실행하세요. 응답에는 청크마다 벡터가 하나씩 이 순서로 들어 있습니다.

curl http://localhost:11434/api/embed -d '{
  "model": "embeddinggemma",
  "input": [
    "Embeddings turn text into numeric vectors. You can store them in a vector database and search them with cosine similarity, or use them in a RAG pipeline.\n\nThe length of each vector depends on the embedding model. Use the same model when you index your documents and when you embed a question.\n\n",
    "Ollama'\''s /api/embed endpoint takes a single string or an array of strings. By default, input that is longer than the model'\''s context window is truncated. Set truncate to false to get an error instead.\n\n",
    "Split long documents into smaller chunks before you embed them, so that each chunk fits in the context window and a search can return the part that answers the question."
  ],
  "truncate": false
}'

청크

청크 3개. 가장 긴 청크는 294자입니다.

  1. #0 · 294자 · 오프셋 0에서 시작

    Embeddings turn text into numeric vectors. You can store them in a vector database and search them with cosine similarity, or use them in a RAG pipeline. The length of each vector depends on the embedding model. Use the same model when you index your documents and when you embed a question.

  2. #1 · 202자 · 오프셋 294에서 시작

    Ollama's /api/embed endpoint takes a single string or an array of strings. By default, input that is longer than the model's context window is truncated. Set truncate to false to get an error instead.

  3. #2 · 169자 · 오프셋 496에서 시작

    Split long documents into smaller chunks before you embed them, so that each chunk fits in the context window and a search can return the part that answers the question.

/api/embed용 JSON 본문

{
  "model": "embeddinggemma",
  "input": [
    "Embeddings turn text into numeric vectors. You can store them in a vector database and search them with cosine similarity, or use them in a RAG pipeline.\n\nThe length of each vector depends on the embedding model. Use the same model when you index your documents and when you embed a question.\n\n",
    "Ollama's /api/embed endpoint takes a single string or an array of strings. By default, input that is longer than the model's context window is truncated. Set truncate to false to get an error instead.\n\n",
    "Split long documents into smaller chunks before you embed them, so that each chunk fits in the context window and a search can return the part that answers the question."
  ],
  "truncate": false
}

/api/embed의 요청 필드는 Ollama API 레퍼런스에 나온 대로이며, 2026-11-04에 확인했습니다. Ollama API: Generate embeddings

모든 작업은 브라우저에서 이루어집니다. 도구는 명령만 작성하며 아무것도 전송하지 않습니다.

Ollama의 /api/embed 엔드포인트는 문자열 하나 또는 문자열 배열을 받으며, API 레퍼런스에 따르면 기본적으로 모델의 컨텍스트 윈도우보다 긴 입력은 잘립니다. 그래서 긴 문서를 문자열 하나로 보내면 오류 없이 끝부분을 잃을 수 있고, 문서 전체를 벡터 하나로 만들면 검색이 질문에 답이 되는 부분만 돌려주기도 어렵습니다. 보통의 해결책은 문서를 더 작은 청크로 나누어 청크마다 임베딩하는 것입니다. 이 도구는 들어맞는 가장 큰 경계에서 텍스트를 나눕니다. 먼저 문단 사이의 빈 줄, 그다음 줄바꿈, 그다음 문장의 끝(。!? 포함), 그다음 공백이며, 글자 단위로 자르는 것은 마지막 수단입니다. 구분 문자를 그대로 두므로, 청크를 다시 이어 붙이면 원래 텍스트가 됩니다. 겹침(오버랩)은 한 청크의 끝부분을 다음 청크의 시작에 조각 단위로 반복해, 경계에서 잘린 문장이 한 청크에는 온전히 들어가도록 합니다. 길이는 글자 수로 셉니다. 결과는 모든 청크를 input 배열에 담은 /api/embed 요청이며, 조용히 잘리는 대신 오류를 원하면 truncate를 false로 설정합니다. 분할은 직접 센 예시로, 그리고 모든 청크가 표시된 위치에서 원문의 일부인지 확인하는 방법으로 검증했습니다.

이 도구의 핵심 로직은 MIT 라이선스의 오픈 소스로 공개되어 있습니다. github.com/seigo5555/toolkitbox-lib/src/text-chunk.ts

이럴 때 사용

  • 매뉴얼, FAQ, README를 내 Ollama 서버에서 RAG 검색에 쓸 수 있게 준비하고, 모든 청크를 요청 한 번으로 임베딩하기
  • 크기를 바꿔 가며 경계가 어디에 놓이는지 보고, 문단이 함께 유지되는 청크 크기 찾기
  • 아무것도 조용히 잘리지 않게 하기: truncate false를 켜면 청크가 모델에 비해 너무 길 때 Ollama가 오류를 반환합니다

사용법

  1. 텍스트를 붙여 넣습니다. 문단은 빈 줄로 구분하면 가능한 한 함께 유지됩니다.
  2. 청크 최대 길이와 겹침을 글자 수로, 임베딩 모델 이름을, 그리고 Ollama 서버가 http://localhost:11434가 아니라면 그 주소를 설정합니다.
  3. curl 명령을 복사해 Ollama에 접근할 수 있는 컴퓨터에서 실행합니다. 응답에는 청크마다 벡터가 하나씩 같은 순서로 들어 있습니다. 이 사이트의 Embedding Similarity Calculator로 그 벡터들을 비교할 수 있습니다.

FAQ

청크 크기는 얼마로 해야 하나요?

딱 맞는 크기는 하나로 정해져 있지 않습니다. 각 청크는 토큰 단위로 세는 모델의 컨텍스트 윈도우 안에 들어가야 하고, 청크가 작을수록 검색이 더 구체적인 문단을 가리킬 수 있습니다. 한두 문단이 함께 유지되는 크기로 시작한 뒤, Embedding Similarity Calculator로 검색 결과를 비교해 보세요.

토큰이 아니라 글자 수로 세는 이유는 무엇인가요?

임베딩 모델마다 토크나이저가 달라 같은 텍스트도 모델에 따라 토큰 수가 다르고, 브라우저 도구가 모든 모델에 대해 정확히 셀 수는 없기 때문입니다. Ollama 라이브러리에는 각 모델의 컨텍스트 윈도우가 토큰 단위로 나와 있습니다. 예를 들어 embeddinggemma와 nomic-embed-text는 2K, mxbai-embed-large와 all-minilm은 512로 나와 있습니다. 여유를 두고, 너무 긴 청크는 truncate false로 찾으세요.

truncate false는 무엇을 하나요?

Ollama API 레퍼런스에 따르면 truncate의 기본값은 true이며, 컨텍스트 윈도우를 넘는 입력을 자릅니다. false이면 Ollama가 대신 오류를 반환합니다. 이 도구는 체크박스를 켜면 "truncate": false를 추가하므로, 너무 긴 청크는 짧아지는 대신 분명하게 실패합니다.

겹침은 어떻게 동작하나요?

새 청크가 시작될 때, 이전 청크의 마지막 조각(문장, 줄, 단어)이 겹침 길이에 들어가고 청크가 최대 길이를 넘지 않는 범위에서 새 청크의 시작에 반복됩니다. 겹침을 채우려고 조각을 자르는 일은 없으므로, 실제 겹침은 설정한 숫자보다 짧을 수 있습니다.

Markdown, HTML, 코드를 이해하나요?

아니요. 모든 것을 일반 텍스트로 취급하고 문단, 줄, 문장, 공백에서 나눕니다. 임베딩에 넣고 싶지 않은 마크업은 텍스트를 붙여 넣기 전에 제거하세요.

내 텍스트가 어딘가로 전송되나요?

아니요. 텍스트는 브라우저에서 나뉘며, 도구는 명령만 작성합니다. 직접 실행하기 전에는 아무것도 전송되지 않습니다.

관련 글

관련 도구