Pinecone 핵심 용어

Pinecone을 처음 쓰기 시작하면 조직(Organization), 프로젝트(Project), 인덱스(Index), 네임스페이스(Namespace) 같은 단어가 연달아 나오는데요. 이 용어들이 서로 어떻게 겹겹이 쌓여 있는지 먼저 짚고 가면 문서를 읽을 때 훨씬 수월해져요. 여기서는 Pinecone의 핵심 객체와 그 관계를 하나씩 풀어볼게요. 각 객체가 실제로 어떻게 중첩되는지는 이 문서의 마지막에 이어질 내용에서 다시 만나요.

출처: Pinecone key terms (공식 문서)

조직 (Organization)

조직은 같은 결제(billing)를 사용하는 하나 이상의 프로젝트(Project)를 묶는 단위예요. 조직에 속한 사용자(User)들은 조직에 소속된 모든 프로젝트의 결제와 권한을 관리해요. '이 조직에 속한 모든 프로젝트를 누가 어떤 권한으로 다룰지'를 정하는 게 조직의 역할이라고 보면 돼요.

프로젝트 (Project)

프로젝트는 조직에 속하면서 하나 이상의 인덱스(Index)를 담는 단위예요. 각 프로젝트는 정확히 하나의 조직에 속하지만, 프로젝트에 속한 사용자만 그 프로젝트의 인덱스에 접근할 수 있어요. 또 중요한 특징이 있는데, API 키(API key)와 어시스턴트(Assistant)는 프로젝트 단위로 분리되어 관리돼요. 즉 키를 어느 프로젝트에서 만들었는지가 접근 범위를 결정해요.

인덱스 (Index)

Pinecone의 서버리스 인덱스는 데이터를 문서(Document) 또는 레코드(Record)로 담아요. 어떤 형태로 담느냐는 인덱스를 어떻게 만들었는지에 따라 달라져요. 문서 스키마로 만든 인덱스(문서 인덱스)는 문서를, dense/sparse 벡터 타입으로 만든 인덱스(벡터 인덱스)는 레코드를 보관해요.

문서는 사용자가 정의한 스키마에 따라 Pinecone이 인덱싱하는 랭킹 필드와, 그 외 메타데이터 필드로 이뤄진 JSON 객체예요. 문서 스키마를 가진 하나의 인덱스는 랭킹 필드 타입을 여러 개 섞을 수 있어요. 의미 검색용 dense_vector 필드, 희소 벡터 검색용 sparse_vector 필드, 그리고 full_text_search가 켜진 string 필드(전문 검색, BM25와 Lucene 쿼리)를 한 레코드 안에 같이 둘 수 있죠. 어떤 다른 필드를 올리든 메타데이터 필드는 업서트(upsert) 시점에 자동으로 인덱싱되어 필터링에 쓰이기 때문에 스키마에 선언할 필요가 없어요.

일반적인 패턴은 '사용 사례 하나당 인덱스 하나'예요. 벡터와 텍스트, 메타데이터를 한 레코드에 함께 담을 수 있으니, 예전에는 인덱스 두 개가 필요했던 일도 하나로 해결되는 경우가 많아요. 쿼리마다 어떤 랭킹 신호를 쓸지는 score_by로 고르면 돼요.

전문 검색 (Full-text search)

전문 검색은 스키마 안의 텍스트 필드에 대해 BM25 토큰 매칭 + Lucene 쿼리 문법을 쓰는 검색이에요. 미리 full_text_search로 선언한 string 필드의 내용을 토큰 단위로 인덱싱해 검색에 쓰는 거예요. 주의할 게 있는데, '텍스트 필드'는 편의상 붙인 이름이고 실제 JSON 타입은 string이에요. 이 검색에는 모델이 필요 없어요. 인덱스 시점에 Pinecone이 토큰화와 IDF, 길이 정규화를 처리하고, 쿼리 시점에는 BM25 스코어링을 직접 계산해요. 여기서 '토큰'은 Pinecone 텍스트 분석기(공백+구두점 분리, 소문자화, 선택적으로 어간 추출)가 만들어내는 단위를 뜻해요. dense/sparse 임베딩 모델이 내부적으로 쓰는 서브워드 단위가 아니라는 점을 구분해 두면 좋아요.

동작 방식을 정리하면 이래요.

JSON 문서로 데이터를 업서트해요.
각 랭킹 필드의 타입을 인덱스 스키마에 선언해요. dense_vector, sparse_vector, 또는 full_text_search가 켜진 string이에요. 메타데이터 필드는 스키마에 선언하지 않아요.
Pinecone은 각 랭킹 필드를 선언한 타입대로 인덱싱하고, 문서의 나머지 필드도 메타데이터 필터링용으로 자동 인덱싱해요.

검색할 때는 score_by로 스코어링 방법을 고르는데, type의 리터럴 값이 방법을 결정해요. text는 텍스트 필드 하나 이상에 대해 BM25 토큰 매칭을, query_string은 여러 텍스트 필드에 걸친 Lucene 쿼리 문법(크로스 필드 불리언 포함)을, dense_vector는 벡터 유사도, sparse_vector는 희소 벡터 유사도를 뜻해요. 어떤 스코어링 방법이든 메타데이터 필터와 조합할 수 있고, 논리 연산자($and, $or, $not), 존재 확인($exists), 텍스트 매칭 연산자($match_phrase, $match_all, $match_any)를 지원해요.

전문 검색은 상품명, 식별자, 기술 용어, 코드처럼 쿼리와 문서가 특정 토큰을 공유하는 키워드·구문 검색에 잘 맞아요. 학습된 인코더(pinecone-sparse-english-v0 등)를 쓰는 희소 벡터 검색이 필요하면 희소 벡터 인덱스를, 자연어 쿼리의 의미 유사도가 필요하면 dense 벡터 인덱스를 보면 돼요.

Dense 벡터 인덱스

이 인덱스들은 각 레코드에 dense 벡터 하나씩 담아요. dense 벡터는 텍스트·이미지·기타 데이터의 의미와 관계를 나타내는 일련의 숫자예요. 각 벡터는 다차원 공간의 한 점이고, 각 숫자는 그 공간의 한 좌표예요. 공간에서 서로 가까운 벡터일수록 의미상 비슷하다고 봐요.

dense 벡터 인덱스를 쿼리하면 Pinecone이 쿼리와 의미상 가장 비슷한 레코드를 찾아줘요. 이걸 보통 의미 검색(semantic search) 또는 최근접 이웃 검색, 유사도 검색, 그냥 벡터 검색이라고 불러요. 레코드에 희소 벡터도 함께 있으면 Vectors API에서 단일 인덱스 하이브리드 검색을 지원해요.

Sparse 벡터 인덱스

이 인덱스들은 각 레코드에 sparse 벡터 하나씩 담아요. 희소 벡터는 차원이 매우 많지만 그중 0이 아닌 값이 몇 개 안 되는 벡터예요. 각 차원은 보통 어휘(vocabulary)의 토큰 하나에 대응하고, 0이 아닌 값은 그 토큰이 문서에서 얼마나 중요한지 나타내요. 대부분 값이 0이기 때문에 Pinecone은 0이 아닌 값과 해당 인덱스만 따로 저장해 효율적으로 보관해요.

sparse 벡터 인덱스를 검색하면 쿼리 벡터와 가중 토큰을 가장 많이 공유하는 레코드를 찾아줘요. 이걸 희소 벡터 검색(sparse-vector search) 이라고 불러요. 희소 벡터는 sparse 임베딩 모델이 만들어내요. Pinecone이 호스팅하는 pinecone-sparse-english-v0는 토큰별 가중치를 예측하고 원문에 없는 관련 개념까지 확장(term expansion)하는 학습된 sparse 인코더예요. 직접 만든 sparse 모델을 가져와 쓸 수도 있어요.

희소 벡터 검색과 전문 검색은 둘 다 토큰 단위 신호를 쓰지만 가중치를 주는 방식이 달라요. 전문 검색은 모델 없는 통계 함수인 BM25를 쓰고, 희소 벡터 검색은 인덱스 시점에 토큰 가중치를 학습하고 관련어로 확장할 수 있는 학습 인코더를 써요. 관리할 게 없고 강력한 기본선이 필요하면 전문 검색을, 도메인의 단어 중요도와 동의어를 학습 인코더가 더 잘 포착한다고 생각되면 희소 벡터를 고르면 돼요.

네임스페이스 (Namespace)

네임스페이스는 인덱스 안의 파티션이에요. 레코드를 별도 그룹으로 나눠서, 각 쿼리가 한 네임스페이스만 스캔하게 해 조회를 빠르게 하고, 고객별 데이터를 서로 격리(멀티테넌트 격리)할 수 있게 해줘요.

모든 업서트와 쿼리, 그리고 다른 데이터 읽기·쓰기 작업은 항상 한 네임스페이스를 대상으로 해요. 네임스페이스를 더 자세히 보려면 인덱싱 개요의 '네임스페이스 사용' 부분을 참고하면 돼요.

레코드 (Record)

레코드는 dense 벡터 인덱스와 sparse 벡터 인덱스의 데이터 단위예요. 레코드 ID, 벡터 하나(또는 단일 인덱스 하이브리드 검색을 위해 두 타입 모두), 그리고 선택적인 메타데이터로 이뤄져요. 통합 임베딩(integrated embedding)을 쓰면 벡터 대신 원본 텍스트를 업서트해도, 인덱스 시점에 Pinecone이 알아서 임베딩해요. 검색 가능한 필드가 여러 개라면(가령 BM25로 랭킹되는 텍스트 필드가 dense_vector 필드와 함께 있는 경우) 문서로 모델링하는 게 좋아요.

레코드 ID

레코드 ID는 레코드의 고유 식별자예요. 저장하는 데이터 유형을 반영하는 ID 접두사를 쓰는 걸 권장해요.

Dense 벡터

dense 벡터는 벡터 임베딩(vector embedding) 또는 그냥 벡터라고도 불러요. 데이터의 의미와 관계를 나타내는 일련의 숫자로, 다차원 공간의 한 점이며 각 숫자는 그 공간의 한 좌표예요. 서로 가까울수록 의미상 비슷한 벡터예요. dense 벡터는 인덱스에 저장되고, dense 임베딩 모델로 데이터를 벡터로 변환해요. 임베딩 모델은 Pinecone 외부에 둘 수도 있고, Pinecone 인프라에 호스팅되어 인덱스와 통합될 수도 있어요.

Sparse 벡터

sparse 벡터는 키워드 정보를 담아 문서나 쿼리를 나타내는 데 자주 쓰여요. 각 차원이 보통 사전의 단어를 나타내고, 0이 아닌 값은 문서에서 그 단어의 중요도를 뜻해요. 차원 수는 많지만 0이 아닌 값이 적어서, Pinecone은 0이 아닌 값과 인덱스만 저장해 효율적으로 관리해요. sparse 벡터는 인덱스에 저장되며, Vectors API의 단일 인덱스 하이브리드 검색을 위해 dense 벡터와 한 인덱스에 함께 있을 수도 있어요. 문서 스키마 인덱스에서 키워드 신호와 dense 신호를 결합하려면 full_text_search가 켜진 string 필드에 텍스트 매칭 필터로 dense 검색을 제한하거나, 별도 검색을 돌려 클라이언트에서 결과를 병합하면 돼요.

기타 개념

Pinecone에는 또 이런 개념들이 있어요.

API 키 (API key) — Pinecone API에 인증하고 접근 권한을 부여하는 고유 토큰이에요. API 키는 프로젝트별로 관리돼요.
사용자 (User) — 조직과 프로젝트의 구성원이에요. 조직/프로젝트 레벨에서 역할을 부여받아 Pinecone 콘솔에서의 권한을 결정해요.
백업 또는 컬렉션 (Backup / collection) — 서버리스 인덱스의 정적 사본이에요. 스토리지만 소비하고 쿼리할 수 없는 레코드 집합의 표현이에요. 인덱스에서 백업을 만들 수 있고, 백업에서 새 인덱스를 만들 수 있어요. 새 인덱스는 이름이 달라도 되지만 소스 인덱스와 차원 수, 유사도 메트릭은 같아야 해요.
Pinecone Inference — Pinecone 인프라에 호스팅된 임베딩 모델과 리랭킹(reranking) 모델에 접근할 수 있게 해주는 API 서비스예요.
읽기 유닛 (RU, Read Unit) — 서버리스 인덱스의 읽기 요청(query, fetch, list) 비용을 측정하고 과금하는 단위예요.
쓰기 유닛 (WU, Write Unit) — 서버리스 인덱스의 쓰기 요청(upsert, update, delete) 비용을 측정하고 과금하는 단위예요.

Pinecone 핵심 용어