Pinecone 인덱스 만들기

Pinecone에서 검색을 시작하려면 먼저 인덱스를 만들어야 해요. 인덱스 하나로 전문 검색(BM25), 의미 검색(dense 벡터), 희소 벡터 검색, 하이브리드 검색을 상황에 맞춰 지원할 수 있어요. 이 문서에서는 문서 스키마 기반 서버리스 인덱스를 만드는 방법을 차근차근 보여드릴게요. 어떤 데이터 형태를 담을 수 있는지부터 인덱스 생성 예시까지 살펴봐요.

출처: Create an index (공식 문서)

인덱스가 담을 수 있는 것들

Pinecone 인덱스는 다음을 조합해 담을 수 있어요.

문서(Document) — 문서 스키마를 가진 인덱스의 데이터 단위예요. 인덱스 생성 시 선언한 스키마에 따라 랭킹 필드를 인덱싱하는 JSON 레코드예요. 문서 스키마 인덱스는 dense_vector, sparse_vector, FTS가 켜진 string 랭킹 필드를 한 레코드에 섞을 수 있고, 업서트 시점에 자동 인덱싱되는 메타데이터 필드도 얼마든지 붙일 수 있어요. full_text_search가 켜진 string 필드의 BM25 랭킹을 쓰는 전문 검색과, score_by로 같은 데이터에 여러 스코어링 방법을 조합하는 데 사용해요.
Dense 벡터 — 텍스트·이미지·기타 데이터의 의미와 관계를 나타내는 수치 표현이에요. dense 벡터 인덱스는 의미 검색에, sparse 벡터와 함께 쓰면 하이브리드 검색에 사용해요.
Sparse 벡터 — 대부분 0 값으로 이뤄진 고차원 벡터로, pinecone-sparse-english-v0 같은 sparse 임베딩 모델이 만들어내요. 희소 벡터 검색에 쓰거나 dense 벡터와 함께 하이브리드 검색에 사용해요.

인덱스는 Pinecone 콘솔에서도 만들 수 있어요.

전문 검색용 인덱스 만들기

문서 스키마를 가진 인덱스는 타입이 정해진 JSON 문서를 보관해요. 스키마는 각 랭킹 필드를 어떻게 인덱싱할지 선언해요. full_text_search가 켜진 string 필드는 BM25 랭킹용, dense_vector는 ANN 유사도용, sparse_vector는 희소 벡터용이에요. 한 인덱스가 세 랭킹 필드 타입을 모두 섞을 수 있고, 쿼리 시점에 score_by로 랭킹 신호를 고르면 돼요. 메타데이터 필드(그 외에 업서트하는 모든 것)는 스키마에 선언하지 않고 업서트 시점에 필터링용으로 자동 인덱싱돼요.

주의할 점이 하나 있어요. 전문 검색은 통합 임베딩(integrated embedding)이 아니에요. full_text_search가 켜진 string 필드는 BM25 랭킹과 Lucene 쿼리를 위해 인덱싱되지, 임베딩 모델을 호출하지 않아요. 통합 임베딩은 벡터 API 인덱스에서 계속 사용할 수 있어요.

문서 스키마 인덱스는 공개 미리보기(public preview) 상태이고 API 버전 2026-01.alpha를 사용해요. 미리보기는 REST와 Python SDK를 지원하고, 다른 언어는 REST 엔드포인트를 직접 호출하면 돼요.

최소 구성: 단일 텍스트 필드에 BM25

아래 예시는 body 필드를 BM25 랭킹용으로 인덱싱하는 articles 인덱스를 만들어요. 업서트 시점에 포함하는 다른 필드는 각 문서에 저장되고 메타데이터로 필터링용으로 자동 인덱싱돼요.

curl -X POST "https://api.pinecone.io/indexes" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Pinecone-Api-Version: 2026-01.alpha" \
  -d '{
    "name": "articles",
    "deployment": {
      "deployment_type": "managed",
      "cloud": "aws",
      "region": "us-east-1"
    },
    "schema": {
      "fields": {
        "body": {
          "type": "string",
          "full_text_search": {}
        }
      }
    }
  }'

다중 필드 스키마: BM25 + dense 벡터

문서 스키마를 가진 하나의 인덱스에 FTS가 켜진 string과 dense_vector 랭킹 필드를 함께 담을 수 있어요. 같은 스키마에 sparse_vector 필드도 추가할 수 있어요. 검색 요청 하나는 스코어링 타입 하나로 랭킹해요. 다중 필드 BM25(서로 다른 필드의 여러 text 절, 또는 필드에 걸친 query_string 절 하나)를 지원하고, 어떤 스코어링 방법이든 FTS string 필드의 텍스트 매칭 필터($match_phrase, $match_all, $match_any)를 포함한 메타데이터 필터와 조합할 수 있어요.

curl -X POST "https://api.pinecone.io/indexes" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Pinecone-Api-Version: 2026-01.alpha" \
  -d '{
    "name": "articles-multi",
    "deployment": {
      "deployment_type": "managed",
      "cloud": "aws",
      "region": "us-east-1"
    },
    "schema": {
      "fields": {
        "title":    { "type": "string", "full_text_search": {} },
        "body":     { "type": "string", "full_text_search": {} },
        "embedding":{ "type": "dense_vector", "dimension": 1536, "metric": "cosine" }
      }
    }
  }'

업서트 시점에 추가 필드(가령 category나 year)를 더 넣을 수 있어요. 모든 메타데이터 필드는 필터링용으로 자동 인덱싱되므로 스키마에 선언할 필요가 없어요. 스키마는 랭킹 필드 전용이에요. 메타데이터 전용 필드(full_text_search 없는 string, string_list, float, boolean)를 스키마에 선언하면 인덱스 생성이 거부돼요.

스키마 마이그레이션은 아직 지원되지 않아요. 문서 스키마 인덱스를 만들고 나면 필드를 추가·제거·수정할 수 없어요. 스키마를 신중히 설계해야 하고, 스키마를 바꿔야 한다면 인덱스를 삭제하고 새로 만드는 방법뿐이에요.

Dense 벡터용 인덱스 만들기

통합 벡터 임베딩으로 dense 벡터를 저장하는 인덱스나, 외부 임베딩 모델이 만든 벡터를 저장하는 인덱스를 만들 수 있어요.

통합 임베딩 (Integrated embedding)

통합 임베딩이 있는 인덱스는 텍스트로 업데이트(update)하거나 가져오기(import)를 지원하지 않아요. 원본 텍스트를 업서트하고 검색하면서 Pinecone이 자동으로 dense 벡터로 변환하길 원한다면, 통합 임베딩으로 인덱스를 만들면 돼요.

from pinecone import Pinecone

pc = Pinecone(api_key="YOUR_API_KEY")

index_name = "integrated-dense-py"

if not pc.has_index(index_name):
    pc.create_index_for_model(
        name=index_name,
        cloud="aws",
        region="us-east-1",
        embed={
            "model":"llama-text-embed-v2",
            "field_map":{"text": "chunk_text"}
        }
    )

핵심 설정을 정리하면 이래요.

인덱스에 name을 지정해요.
인덱스를 배포할 cloud와 region을 cloud/region으로 설정해요.
embed.model을 Pinecone의 호스팅 임베딩 모델 중 하나로 설정해요.
embed.field_map을 임베딩할 데이터가 담긴 원본 문서의 필드 이름으로 설정해요.

Pinecone 호스팅 임베딩 모델

multilingual-e5-large — 100개 이상의 언어를 지원하는 dense 임베딩 모델로, 다국어 의미 검색에 탁월해요. 벡터 타입은 Dense, 모달리티는 Text, 권장 유사도 메트릭은 Dotproduct, 최대 시퀀스 길이는 512, 최대 배치 크기는 96 시퀀스예요. input_type(query/passage), truncate(END/NONE), dimension 파라미터를 지원해요.
llama-text-embed-v2 — 텍스트를 dense 벡터로 변환하는 모델이에요. 벡터 타입은 Dense, 모달리티는 Text, 권장 유사도 메트릭은 Dotproduct, 최대 시퀀스 길이는 8192, 최대 배치 크기는 96 시퀀스예요. input_type(query/passage), truncate(END/NONE), dimension 파라미터를 지원해요. dimension 기본값은 1024예요.
pinecone-sparse-english-v0 — 텍스트를 희소 벡터로 변환하는 sparse 임베딩 모델로, 희소 벡터 검색이나 하이브리드 검색에 써요. DeepImpact 아키텍처를 기반으로, BM25처럼 단순 빈도에만 의존하지 않고 문맥을 활용해 토큰의 어휘 중요도를 직접 추정해요. 벡터 타입은 Sparse, 모달리티는 Text, 권장 유사도 메트릭은 Dotproduct, 최대 시퀀스 길이는 512 또는 2048, 최대 배치 크기는 96 시퀀스예요. input_type(query/passage), max_tokens_per_sequence(512/2048, 기본 512), truncate(END/NONE), return_tokens 파라미터를 지원해요.

Pinecone 인덱스 만들기