검색 - Conare

POST /namespaces/:namespace/query 의미와 키워드로 네임스페이스를 검색합니다. Conare가 상위 일치 항목을 리랭킹하고 각 문서에서 답이 되는 구절을 반환합니다.

curl https://api.conare.ai/namespaces/docs/query \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "how do refunds work?", "top_k": 5, "filter": {"team": "support"}}'

const results = await docs.query("how do refunds work?", {
  topK: 5,
  filter: { team: "support" },
});

Response

{
  "results": [
    {
      "id": "refunds",
      "text": "Refunds are available for 30 days.",
      "score": 0.3192,
      "reranked": true,
      "metadata": { "team": "support" }
    }
  ],
  "took_ms": 62
}

옵션

옵션	타입	기능
`query`	string, 필수	최대 8,000자의 질문
`top_k`	integer, 기본값 10	반환할 결과 수, 1-500
`filter`	object	메타데이터 필터
`user`	string	이 사용자의 문서만
`user_prefix`	string	`tenant-7:`처럼 이 값으로 시작하는 사용자만
`answer`	boolean, 기본값 `false`	답변 작성도 함께 합니다
`rerank`	boolean, 기본값 `true`	상위 일치 항목을 리랭킹합니다. `false`가 더 빠릅니다
`rerank_depth`	integer, 기본값 20	리랭킹할 상위 구절 수, 1-1,000
`hops`	integer, 기본값 1	`2`는 상위 결과에서 다시 검색합니다(투 홉)
`retrievers`	array, 기본값 `["vector", "keyword"]`	`vector`(의미)와 `keyword` 중 1개 또는 2개
`exclude_ids`	array	제외할 문서 id, 최대 10,000개
`max_results`	integer	최대 1,000개의 결과를 페이지로 탐색합니다. 맞춤 모델은 5,000개
`cursor`	string	이전 페이지의 `next_cursor`

전체 스키마: 네임스페이스 쿼리.

응답

필드	의미
`results`	가장 좋은 것부터, 문서당 하나
`results[].id`, `metadata`, `user`	해당 문서의 값
`results[].text`	답이 되는 구절을 가장 좋은 것부터 반환합니다. 가장 좋은 구절과 거의 비슷하게 일치하는 최대 2개이며, 각각 최대 약 3,000바이트입니다. 이어지지 않는 구절 사이에는 `…`만 있는 줄이 들어갑니다. 전체는 문서를 가져오세요
`results[].score`	높을수록 좋습니다. 같은 쿼리 안에서만 비교하세요
`results[].reranked`	리랭커가 점수를 매겼는지 여부. 리랭킹되지 않은 결과는 마지막에 옵니다
`answer`	`answer: true`일 때의 답변
`next_cursor`	`max_results` 사용 시 다음 페이지의 `cursor`. 마지막 페이지에서는 생략됩니다
`took_ms`	검색 시간(밀리초)

답변

"answer": true는 상위 구절로 작성한 답변을 추가하며, 약 2초가 더 걸립니다.

Response

{
  "answer": "Refunds are available for 30 days (source dated 2026-10-21). No further details on the refund process, conditions, or method were found in this search.",
  "results": [ ... ],
  "took_ms": 1546
}

찾은 구절을 바탕으로 언어 모델이 답변을 작성합니다. 개인정보 처리방침을 참조하세요.
해당 모델을 사용할 수 없으면 answer 없이 결과만 받습니다.

투 홉

"hops": 2는 상위 결과에서 다시 검색합니다. 두 문서의 사실이 필요한 질문에 사용합니다.

curl

curl https://api.conare.ai/namespaces/films/query \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "where was the director of The Long Harbor born?", "hops": 2}'

약 0.3초가 추가됩니다. 사실을 연결해야 하는 질문에 사용하세요.
rerank: false, max_results와 함께 쓰거나 맞춤 모델의 네임스페이스에서 쓰면 400 invalid_request를 반환합니다.

페이지

단계	보낼 값
첫 페이지	`query`, `max_results`(한 번에 순위를 매길 개수), `top_k`(페이지 크기)
다음 페이지	`cursor`(마지막 `next_cursor`)와 `top_k`만
마지막 페이지	`next_cursor`가 없습니다

커서는 15분 동안 유효합니다. SDK의 queryPages()는 모든 페이지를 읽습니다.

모든 네임스페이스 검색

POST /query 같은 요청을 최대 100개 네임스페이스에 걸쳐 실행하고 함께 리랭킹합니다. prefix는 이름이 해당 값으로 시작하는 네임스페이스로 제한합니다.

curl

curl https://api.conare.ai/query \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "how do refunds work?", "prefix": "acme-"}'

Response

{
  "namespaces": ["acme-docs"],
  "results": [
    {
      "namespace": "acme-docs",
      "id": "refunds",
      "text": "Refunds are available for 30 days.",
      "score": 0.3471,
      "reranked": true,
      "metadata": { "team": "support" }
    }
  ],
  "skipped_namespaces": [],
  "took_ms": 64
}

옵션 또는 필드	여기서는
`prefix`	이름이 이 값으로 시작하는 네임스페이스만
`rerank_depth`	기본값 60, 1-1,000
`exclude_ids`	`namespace/id` 형식으로 작성
`results[].namespace`	결과의 네임스페이스
`namespaces`, `skipped_namespaces`	검색된 네임스페이스와 처음 100개를 넘은 네임스페이스

hops도 여기서 작동합니다. 전체 스키마: 모든 네임스페이스 쿼리.

저하된 결과

검색 일부가 실패해도 쿼리는 성공하며, Conare-Degraded 헤더가 건너뛴 부분을 알려 줍니다.

값	의미
`rerank`, `rerank-partial`	일부 또는 모든 결과가 리랭킹되지 않음(`reranked: false`)
`embed`	키워드로만 검색함
`keyword`, `keyword-terms`	쿼리가 너무 길어 키워드 검색이 전체를 읽지 못함
`embed-next`	네임스페이스 일부를 검색할 수 없었음
`cursor`	`next_cursor` 없음. 더 많은 페이지는 다시 검색하세요
`embed-busy`, `embed-fallback`	평소보다 느림. 결과에는 영향 없음
`answer`	답변 없이 결과만

아무것도 검색할 수 없으면 쿼리는 503을 반환합니다.

시작하기

핵심

파일

동기화

모델

도구

검색

옵션

응답

답변

투 홉

페이지

모든 네임스페이스 검색

저하된 결과

​옵션

​응답

​답변

​투 홉

​페이지

​모든 네임스페이스 검색

​저하된 결과

옵션

응답

답변

투 홉

페이지

모든 네임스페이스 검색

저하된 결과