Retrieval: 인덱스 위의 하이브리드 검색

문서를 인덱스에 넣고 나면, 이제 질문에 맞는 조각을 뽑아내야 해요. Retrieval 엔드포인트는 벡터 유사도 검색과 전문(full-text) 검색을 결합한 하이브리드 검색을 수행해요. 기본 제공 필드나 사용자 정의 메타데이터로 필터링하고, 리랭킹을 적용해 관련성을 한 단계 더 높일 수도 있어요.

출처: 공식문서

MCP 호환 에이전트는 LlamaParse MCP의 retrieveFromIndex 도구로 SDK 코드 없이 같은 하이브리드 검색을 쓸 수 있어요.

기본 검색

results = await client.beta.retrieval.retrieve(
    index_id="<your-index-id>",
    query="What were the Q3 revenue figures?",
    top_k=10,
)

for result in results.results:
    print(f"Score: {result.score}, Rerank: {result.rerank_score}")
    print(result.content)

주요 파라미터

파라미터	타입	기본값	설명
`index_id`	`string`	필수	검색할 인덱스 ID.
`query`	`string`	필수	자연어 질의.
`top_k`	`int`	서버 기본값	반환할 최대 결과 수.
`vector_pipeline_weight`	`float`	`null`	벡터 검색 가중치 (0—1).
`full_text_pipeline_weight`	`float`	`null`	전문 검색 가중치 (0—1).
`score_threshold`	`float`	`null`	반환 결과의 최소 점수.
`num_candidates`	`int`	`null`	ANN 후보 수 (높을수록 정확하지만 느림).

리랭킹

리랭킹은 기본으로 켜져 있어요. 하이브리드 검색이 후보를 뽑으면 리랭커 모델이 그 후보를 다시 채점해서 관련성을 개선해요.

# 리랭킹 끄기
results = await client.beta.retrieval.retrieve(
    index_id="<your-index-id>",
    query="summary of findings",
    rerank={"enabled": False},
)

# 리랭킹 유지 + 상위 3개로 제한
results = await client.beta.retrieval.retrieve(
    index_id="<your-index-id>",
    query="summary of findings",
    rerank={"enabled": True, "top_n": 3},
)

필터링

내장 정적 필드나 사용자 정의 메타데이터로 결과를 좁힐 수 있어요.

정적 필터는 모든 청크에 저장된 내장 필드를 대상으로 해요. 현재는 parsed_directory_file_id를 지원해서, 특정 파일로 검색 범위를 제한할 수 있어요.

results = await client.beta.retrieval.retrieve(
    index_id="<your-index-id>",
    query="revenue breakdown",
    static_filters={
        "parsed_directory_file_id": {"operator": "eq", "value": "<file-id>"},
    },
)

사용자 정의 메타데이터 필터는 파일이 디렉토리에 추가될 때 붙은 사용자 정의 메타데이터와 대조해요.

results = await client.beta.retrieval.retrieve(
    index_id="<your-index-id>",
    query="contract terms",
    custom_filters={
        "category": {"operator": "eq", "value": "legal"},
        "year": {"operator": "gte", "value": 2024},
    },
)

응답 형식

각 결과는 다음 필드를 담아요.

필드	설명
`content`	검색된 청크의 텍스트 본문.
`score`	하이브리드 검색 관련성 점수.
`rerank_score`	리랭커 점수 (리랭킹을 적용한 경우).
`metadata`	청크에 연결된 사용자 정의 메타데이터.
`static_fields.parsed_directory_file_id`	이 청크가 속한 파싱 파일의 ID.
`static_fields.page_range_start` / `page_range_end`	청크가 덮는 페이지 범위.
`static_fields.chunk_index`	파일 내 청크의 위치.
`static_fields.chunk_token_count`	청크의 토큰 수.

더 알아보기

Index 시작 가이드 — 디렉토리·인덱스·검색 3단계 모델
Chat — 인덱스 위에서 도는 내장 RAG 에이전트