Response Shaping(응답 형태 조정)

Show: All versions v2 only

Response shaping(응답 형태 조정)으로 버킷(bucket) 검색 엔드포인트(endpoint)가 반환하는 내용과 각 결과의 형식을 제어할 수 있습니다. 더 작은 페이로드를 위해 필드를 생략하거나, 형식이 지정된 인용(citation)을 삽입하고, 검색된 청크(chunk)의 그래프 이웃(neighbor)을 함께 가져오는 데 사용하세요.

참고: context, citations, status, operational_status가 포함된 완전한 답변 컨텍스트(context)가 필요하면 Query & Search 엔드포인트를 사용하세요. 버킷 검색 엔드포인트는 정렬된 원시 청크(raw ranked chunks)를 반환하며, 다운스트림 조립(downstream assembly)을 직접 처리할 때 더 적합합니다.

API 버전

버전	상태	설명
v2	Current(현재)	POST /v2/buckets/\{bucket_id\}/search. 모든 신규 연동에 사용하세요.
v1	Deprecated(사용 중단)	POST /v1/buckets/\{bucket_id\}/search는 기존 클라이언트를 위해 유지되며, v2 후속 버전을 가리키는 Deprecation, Warning, Link 헤더를 반환합니다.

POST /v2/buckets/{bucket_id}/search

버킷을 검색하고 반환되는 청크의 형태를 조정합니다.

경로 매개변수

이름	타입	설명
bucket_id	string	검색할 버킷(bucket)의 UUID 또는 슬러그(slug).

요청 헤더

헤더	값
Authorization	Bearer $SCHIFT_API_KEY
Content-Type	application/json

요청 본문

필드	타입	필수	기본값	설명
query	string	Yes(예)	—	자연어 쿼리(query). 최대 8,192자.
top_k	integer	No(아니오)	10	반환할 최대 결과 수(1–1000).
mode	string	No(아니오)	"hybrid"	"vector" 또는 "hybrid".
rerank	boolean	No(아니오)	false	후보를 재정렬(rerank)할지 여부.
min_score	number	No(아니오)	null	최소 점수 임계값(0.0–1.0).
include_fields	array of string	No(아니오)	null	결과 필드 화이트리스트(whitelist), 예: ["id", "score", "metadata.title"]. 레거시 원시 결과 제어.
exclude_fields	array of string	No(아니오)	null	결과 필드 블랙리스트(blacklist), 예: ["text", "metadata.source_url"]. 레거시 원시 결과 제어.
citation_format	string	No(아니오)	null	결과별 citation 템플릿, 예: "[\{title\}:p.\{page\}]". 레거시 원시 결과 제어.
expand_neighbors	object	No(아니오)	null	각 검색 결과의 그래프 이웃(neighbor)을 가져옵니다. 이웃 확장을 참조하세요.
expand_context	object	No(아니오)	null	재정렬(rerank) 전 동일 문서의 인접 청크를 추가합니다.
debug	boolean	No(아니오)	false	상세한 디버그(debug) 시간 및 청크별 점수를 포함합니다.

응답

필드	타입	설명
bucket_id	string	검색된 버킷.
query	string	실행된 쿼리(query).
search_id	string | null	서버에서 생성한 검색 식별자.
results	array	관련성순으로 정렬된 일치 청크(chunk).
results[].id	string	청크 식별자.
results[].score	number	최종 관련성 점수.
results[].text	string	청크 텍스트.
results[].metadata	object	bucket_id와 collection_id를 포함한 청크 메타데이터(metadata).
results[].citation	string | null	citation_format 설정 시 형식이 지정된 인용(citation).
results[].neighbors	array | null	expand_neighbors 설정 시 그래프 이웃(neighbor).
degraded	boolean	응답이 저하 모드(degraded)로 생성되었는지 여부.
warnings	array	검색 경고(있는 경우).
debug	object | null	debug: true일 때의 디버그(debug) 정보.

필드 투영(projection)

include_fields와 exclude_fields는 각 결과에 어떤 키가 나타날지 제어합니다. 둘 다 metadata.title과 같은 점 표기 경로(dotted path)를 지원합니다.

• include_fields는 키를 화이트리스트(whitelist)에 등록합니다. 설정하면 나열된 최상위 키와 요청한 메타데이터(metadata) 하위 키만 반환됩니다.
• exclude_fields는 키를 블랙리스트(blacklist)에 등록합니다. 설정하면 나열된 최상위 키와 메타데이터 하위 키가 제거됩니다.
• 둘 다 설정된 경우 include_fields가 우선합니다.

참고: id, score, text는 항상 기본값으로 채워지므로, 투영(projection)으로 인해 제거되더라도 결과가 유효하게 유지됩니다.

인용(citation) 형식

citation_format가 제공되면 각 결과에 \{key\} 토큰을 치환하여 만들어진 citation 문자열이 추가됩니다. 토큰은 먼저 결과에서, 그다음에 metadata에서 해석됩니다. 알 수 없는 토큰은 빈 문자열로 렌더링됩니다.

예를 들어 메타데이터(metadata)가 {"title": "Terms", "page": 3}이고 형식이 "[\{title\}:p.\{page\}]"라면 인용(citation)은 "[Terms:p.3]"이 됩니다.

이웃(neighbor) 확장

expand_neighbors는 각 검색 결과에 연결된 그래프 엣지(edge)를 가져옵니다.

필드	타입	필수	기본값	설명
relations	array of string	No(아니오)	null	이 관계 타입으로 필터링합니다. null은 모두를 의미합니다.
direction	string	No(아니오)	"both"	"outgoing", "incoming", "both" 중 하나.
max_per_hit	integer	No(아니오)	10	결과당 반환할 최대 엣지 수(1–100).

반환된 각 이웃(neighbor)은 다음을 포함합니다.

필드	타입	설명
id	string	이웃 노드 ID.
relation	string	관계 타입, 예: follows, has_child.
direction	string	"outgoing" 또는 "incoming".
weight	number	엣지 가중치.

예제 요청

curl -X POST ${API_BASE_URL:-https://api.schift.io}/v2/buckets/product-docs/search \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "annual leave policy",
    "top_k": 5,
    "min_score": 0.7,
    "citation_format": "[{title}:p.{page}]",
    "expand_neighbors": {
      "relations": ["references", "has_child"],
      "direction": "both",
      "max_per_hit": 3
    },
    "debug": true
  }'

예제 응답

{
  "bucket_id": "product-docs",
  "query": "annual leave policy",
  "search_id": "search_0a1b2c3d4e5f",
  "results": [
    {
      "id": "chunk_01j8x9q2mvn9q",
      "score": 0.91,
      "text": "Full-time employees receive 20 days of paid annual leave per year.",
      "metadata": {
        "bucket_id": "product-docs",
        "collection_id": "col_123",
        "title": "Employee Handbook",
        "page": 12,
        "doc_type": "policy"
      },
      "citation": "[Employee Handbook:p.12]",
      "neighbors": [
        {
          "id": "chunk_01j8x9q2mvna0",
          "relation": "references",
          "direction": "outgoing",
          "weight": 1.0
        }
      ]
    }
  ],
  "degraded": false,
  "warnings": [],
  "debug": {
    "query_embedding_model": "schift-embed-v1",
    "search_method": "hybrid",
    "timing_ms": {
      "embedding": 23,
      "vector_search": 18,
      "bm25": 9,
      "hydration": 4,
      "total": 62
    },
    "results_detail": [
      {
        "chunk_id": "chunk_01j8x9q2mvn9q",
        "vector_score": 0.88,
        "bm25_score": 0.72,
        "rrf_score": 0.85,
        "final_score": 0.91,
        "source": "hybrid"
      }
    ]
  }
}

오류 예제

// 400 Bad Request — missing query
{
  "detail": "query or query_vector is required"
}

// 400 Bad Request — invalid filter
{
  "detail": "Invalid filter: unsupported operator"
}

// 402 Payment Required — search quota exhausted
{
  "allowed": false,
  "reason": "quota_exceeded"
}

// 403 Forbidden — search quota unavailable
{
  "detail": "Search quota unavailable. Upgrade your plan."
}

// 404 Not Found
{
  "detail": "Bucket not found"
}

// 500 Internal Server Error
{
  "detail": "Bucket search failed"
}

레거시 v1 엔드포인트

POST /v1/buckets/\{bucket_id\}/search는 사용 중단(deprecated)되었습니다. 동일한 페이로드(payload) 형태를 반환하지만 다음 응답 헤더가 추가됩니다.

헤더	값
Deprecation	true
Warning	299 - "Deprecated search endpoint; migrate to /v2/buckets/\{bucket_id\}/search"
Link	</v2/buckets/\{bucket_id\}/search>; rel="successor-version"

참고 항목

• Buckets
• Query & Search
• Filter Operators
• Metadata
• Edges