문서

검색

자연어, 사전 계산된 벡터, 하이브리드 모드, 리랭킹, 시간 제약을 사용하여 컨렉션을 검색합니다.

벡터 검색

bashPOST /v1/query

쿼리를 임베딩하고 컨렉션의 벡터 공간으로 프로젝션한 후 가장 유사한 결과를 반환합니다. 텍스트 쿼리, 사전 계산된 벡터, 하이브리드 검색, 크로스 인코더 리랭킹, 시간 필터링을 지원합니다.

파라미터	타입	필수	기본값	설명
`query`	string	아니오*	--	자연어 검색 텍스트
`query_vector`	float[]	아니오*	--	사전 계산된 임베딩 (임베딩 단계 생략)
`collection`	string	예	--	검색할 컨렉션 이름
`model`	string	아니오	조직 설정	임베딩 모델
`top_k`	integer	아니오	10	반환할 결과 수
`mode`	string	아니오	vector	`vector` 또는 `hybrid` (벡터 + BM25 RRF)
`rerank`	boolean	아니오	false	크로스 인코더 리랭킹 활성화
`rerank_top_k`	integer	아니오	top_k	리랭킹 후 유지할 결과 수
`rerank_model`	string	아니오	--	리랭커 모델 오버라이드
`temporal`	string	아니오	--	`before`, `after`, `between`, `as_of`, `latest`
`temporal_start`	integer	아니오	--	에포크 밀리초 (latest 제외 temporal 설정 시 필수)
`temporal_end`	integer	아니오	--	에포크 밀리초 (between에 필수)

참고

query 또는 query_vector 중 하나는 필수입니다. 하이브리드 모드와 리랭킹은 텍스트 쿼리가 필요합니다.

기본 검색

bashcurl -X POST https://api.schift.io/v1/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{
    "query": "임베딩 모델 마이그레이션 방법",
    "collection": "product-docs",
    "top_k": 5
  }'

사전 계산된 벡터

사전 계산된 벡터를 직접 전달하여 임베딩 단계를 생략합니다. 벡터는 컨렉션 차원에 맞게 프로젝션됩니다.

bashcurl -X POST https://api.schift.io/v1/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{
    "query_vector": [0.1, 0.2, ...],
    "collection": "product-docs",
    "top_k": 5
  }'

하이브리드 검색

벡터 유사도와 BM25 키워드 매칭을 Reciprocal Rank Fusion으로 결합합니다. 후보를 3배 오버페치한 후 병합합니다.

bashcurl -X POST https://api.schift.io/v1/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{
    "query": "근로계약 해지 조항",
    "collection": "legal-docs",
    "mode": "hybrid",
    "top_k": 10
  }'

리랭킹

크로스 인코더 모델로 결과를 재평가하여 정밀도를 높입니다. 결과에 원래 score와 rerank_score가 모두 포함됩니다.

bashcurl -X POST https://api.schift.io/v1/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{
    "query": "데이터 보존 정책",
    "collection": "compliance",
    "rerank": true,
    "rerank_top_k": 3
  }'

시간 기반 검색

event_time 메타데이터로 결과를 필터링합니다. event_time이 없는 벡터는 temporal 쿼리에서 제외됩니다.

bash# 최근 7일간 문서
curl -X POST https://api.schift.io/v1/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{
    "query": "최근 정책 변경",
    "collection": "policies",
    "temporal": "after",
    "temporal_start": 1711324800000
  }'

# 특정 기간 내 문서
curl -X POST https://api.schift.io/v1/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{
    "query": "분기 보고서",
    "collection": "finance",
    "temporal": "between",
    "temporal_start": 1704067200000,
    "temporal_end": 1711929600000
  }'

크로스 모델 검색

모든 벡터는 Schift의 정규 프로젝션 레이어를 통과합니다. 한 임베딩 모델로 저장한 문서를 다른 모델로 검색할 수 있습니다.

bash# OpenAI로 저장된 문서를 다른 모델로 검색
curl -X POST https://api.schift.io/v1/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -d '{
    "query": "임베딩 모델 마이그레이션",
    "collection": "product-docs",
    "model": "voyage/voyage-4-large",
    "top_k": 3
  }'