Knowledge Retrieval API 외부 서비스 연동 가이드¶
질문 하나로 Procedure Hub의 전체 게시 지식에서 관련 자료를 찾는 read-only API다. 호출 서비스가 시술·안전·문헌 같은 검색 분야를 미리 지정할 필요는 없다.
이 API는 답변을 생성하지 않는다. 다른 서비스가 검색 결과를 표시하거나 AI 답변을 만들 때 사용할 지식 본문·출처·안전 규칙을 반환한다.
1. 바로 사용하기¶
POST {backend-host}/procedure-hub/api/v1/knowledge/retrieve
Content-Type: application/json
STG endpoint:
https://api-stg-csp.medisolveai.com/procedure-hub/api/v1/knowledge/retrieve
권장 요청:
{
"query": "보톡스와 필러를 같이 하려면 순서와 주의점이 뭐야?",
"lang": "ko",
"max_results": 40,
"fields": ["interpretation", "items", "sources", "safety", "retrieval"]
}
curl --request POST \
'https://api-stg-csp.medisolveai.com/procedure-hub/api/v1/knowledge/retrieve' \
--header 'content-type: application/json' \
--data '{
"query": "기미 환자에게 레이저 시술 시 주의할 점은?",
"lang": "ko",
"max_results": 40,
"fields": ["interpretation", "items", "sources", "safety", "retrieval"]
}'
응답을 사용할 때는 다음 핵심 값만 먼저 보면 된다.
status 결과를 정상 사용해도 되는지 판단하는 상태
interpretation API가 질문에서 인식한 의도·시술과 모호한 용어
items 질문과 관련된 실제 지식
sources 지식의 출처
safety 반드시 별도로 확인할 안전 규칙
limitations 현재 결과만으로 확정할 수 없는 내용
data_revision 검색에 사용된 게시 데이터 버전
request_id 장애·결과 추적 ID
2. 검색될 수 있는 정보 종류¶
한 질문에 관련된 여러 종류의 정보가 함께 반환될 수 있다.
| 종류 | 포함될 수 있는 내용 |
|---|---|
| 시술·제품 기본정보 | 시술 코드·분류·이름·특성, 제품·제조사 |
| 시술별 임상정보 | 기전, 효과, 방법, 깊이·용량, 위험, 회복·주의사항 |
| 조합·추천정보 | 고민별 패키지, 시술 조합·시너지·비교·최적화, 가격 범위 |
| 안전·사전확인 | 금기, 병행 간격·순서, 위험부위, 합병증, PIH 위험, 사전·동의 체크리스트 |
| 사후관리·환자안내 | 시술 후 경과, 회복 단계, 즉시 대응, 환자 안내사항 |
| 검증 문헌 | 검증된 임상 주장, 논문 제목, PMID·DOI 등 출처 |
시술별 임상정보에는 현재 보톡스, 필러, 바이오스티뮬레이터, 스킨부스터, PRP, 지방이식, 실리프팅, 레이저, 에너지기기, HIFES, 니들RF, MTS, 플라즈마, 크라이오, 스킨케어, 정맥주사요법, 줄기세포의 17개 시술군이 포함된다.
예시:
- 병용 질문 → 조합, 순서·간격, 금기, 관련 문헌
- 부작용 질문 → 합병증, 즉시 대응, 사후관리, 관련 문헌
- 고민·추천 질문 → 시술·제품 정보, 패키지, 비교, 가격
질문과 관련도 기준을 통과한 정보만 반환되므로 모든 종류가 매번 오는 것은 아니다.
3. 요청 필드¶
| 필드 | 필수 | 의미 |
|---|---|---|
query |
O | 자연어 질문. 1~500자 |
lang |
X | 요청 언어 코드. 기본 ko |
max_results |
X | 한 페이지 결과 수. 기본 40, 범위 1~200 |
cursor |
X | 다음 페이지 조회 시 이전 응답의 retrieval.next_cursor |
fields |
X | 응답에서 받을 정보 묶음 선택 |
fields는 검색할 분야를 제한하는 값이 아니다. 전체 지식은 그대로 검색하고, 응답에서
어떤 설명 묶음을 받을지만 정한다.
fields 값 |
쉽게 말하면 | 사용처 |
|---|---|---|
items |
“질문과 관련된 정보가 무엇인가?” | 검색 결과·AI context |
sources |
“이 정보는 어디에서 왔는가?” | 출처·근거 표시 |
safety |
“무엇을 반드시 확인해야 하는가?” | 의료 안전 안내 |
interpretation |
“API가 질문을 어떻게 이해했는가?” | 인식한 시술·의도·모호성 확인 |
retrieval |
“몇 건을 찾았고 다음 결과가 있는가?” | 페이지네이션·검색 진단 |
coverage |
“어떤 지식 영역까지 검색했는가?” | 운영·검색 품질 점검 |
권장 조합:
| 목적 | fields |
|---|---|
| 일반 검색 | items, sources |
| 의료 관련 AI·상담 기능 | items, sources, safety |
| 다음 페이지 사용 | 위 조합에 retrieval 추가 |
| 검색 검사 화면 | 생략하여 전체 응답 |
- 생략 또는
null: 모든 묶음 반환 - 빈 배열
[]: 공통 필드만 반환 - 선택하지 않은 묶음:
null이 아니라 응답에서 제외 - 출처가 필요하면
items와sources를 함께 요청
query는 trim 후 전송하고 환자 이름·연락처·주민등록번호 같은 개인식별정보는 포함하지
않는다. 현재 검색 ranking은 한국어에 최적화되어 있다.
4. 응답 필드¶
공통 필드¶
이 필드들은 fields 선택과 관계없이 항상 반환된다.
| 필드 | 의미 | 사용 방법 |
|---|---|---|
request_id |
요청 추적 ID | 서비스 로그와 장애 문의에 기록 |
status |
검색 업무 상태 | 아래 상태표에 따라 분기 |
query |
서버가 처리한 질문 | 결과 화면·로그에 사용 |
limitations |
데이터·검색 한계 | 사용자 안내 또는 AI prompt에 포함 |
data_revision |
게시 release의 ID·버전·게시 시각 | 결과 재현·감사·캐시에 사용 |
items: 실제 지식¶
| 필드 | 의미 |
|---|---|
ref |
item 식별값. 페이지 결과를 합칠 때 중복 제거 키로 사용 |
domain |
정보가 나온 지식 영역 |
kind |
자료 종류. 예: safety_rule, verified_claim, packages |
title |
결과 제목 |
content |
화면 또는 AI context에 사용할 본문 |
attributes |
간격·가격·중증도 등 자료 종류별 구조화 값 |
entity_refs |
연결된 시술·고민·제품 ID |
source_refs |
출처 reference |
relevance.score |
질문과 item의 검색 관련도. 0~1 |
relevance.reasons |
제목 일치, entity 연결, 안전 규칙 강제 포함 등 포함 이유 |
attributes 구조는 domain과 kind마다 다르다. 공통 소비자는 title, content,
source_refs를 사용하고 특정 구조 값이 필요한 서비스만 종류별 adapter를 둔다.
relevance.score는 의료 근거 수준·안전도·추천 강도가 아니다. 서버가 일반 결과에 이미
0.9 기준을 적용하므로 별도 제품 요구가 없다면 소비자가 다시 필터링하지 않는다.
sources: 출처¶
| 필드 | 의미 |
|---|---|
source_id |
item의 source_refs와 연결할 출처 ID |
domain |
출처 지식 영역 |
title |
게시 자료 또는 문헌 제목 |
locator |
원문 URL 또는 내부 위치. 없을 수 있음 |
revision_id |
내부 게시 revision UUID. 외부 문헌은 없을 수 있음 |
verification_status |
published_revision 또는 verified_evidence |
모든 source_refs가 상세 source로 확장되지는 않는다. 매칭되는 source_id가 없으면 임의로
URL을 만들지 않는다.
safety: 안전 규칙¶
| 필드 | 의미 |
|---|---|
status |
needs_confirmation, restricted, indeterminate 중 하나 |
item_refs |
items 중 안전 규칙으로 포함된 item |
required_checks |
결과 사용 전에 확인해야 할 공통 임상 항목 |
limitations |
안전 규칙만으로 판단할 수 없는 내용 |
safety.status |
의미 |
|---|---|
restricted |
경고 수준의 규칙이 있음 |
needs_confirmation |
관련 규칙이 있으나 환자별 의료진 확인이 필요함 |
indeterminate |
등록 규칙만으로 안전성을 판단할 수 없음 |
규칙이 검색되지 않았다는 사실을 “안전함” 또는 “병용 가능”으로 해석하면 안 된다.
나머지 선택 필드¶
| 필드 | 포함 정보 |
|---|---|
interpretation |
감지한 질문 의도, 인식한 시술·고민·제품, 모호하거나 매칭되지 않은 용어 |
retrieval |
검색 전략, 후보·반환 수, 잘림 여부, 다음 페이지 cursor |
coverage |
지식 영역별 검색 역할과 매칭 결과 수 |
5. 상태와 오류 처리¶
HTTP 200이어도 status를 확인한다.
status |
의미 | 처리 |
|---|---|---|
ok |
관련 정보를 정상 조회함 | 결과 사용 |
no_match |
관련 결과가 없음 | 질문을 바꿔 다시 검색하도록 안내 |
needs_clarification |
용어가 여러 대상으로 해석됨 | interpretation을 보고 재질문 |
partial |
결과는 있으나 일부 정보가 부족함 | limitations와 함께 사용 |
unavailable |
게시 release가 없음 | 결과 사용 중단 |
error |
검색 실패를 위한 예약 상태 | 실패 처리·로그 확인 |
| HTTP | 의미 | 처리 |
|---|---|---|
400 |
cursor가 query 또는 release와 맞지 않음 | cursor 없이 첫 페이지 재조회 |
422 |
요청값 검증 실패 | query·범위·fields 수정 |
500 |
Backend 내부 오류 | 로그 확인 후 제한적으로 재시도 |
502 |
Procedure Hub 화면 BFF의 Backend 연결 실패 | Backend health·BFF 설정 확인 |
6. 소비 서비스 처리 순서¶
1. HTTP 상태 확인
2. body.status 확인
3. items를 화면 또는 AI context로 사용
4. source_refs와 sources를 연결해 출처 제공
5. safety와 limitations를 사용자 안내 또는 AI prompt에 포함
6. request_id와 data_revision을 로그에 기록
7. next_cursor가 있으면 같은 query로 다음 페이지 조회
AI 답변에 사용할 최소 정보:
items[].title + items[].content
필요한 items[].attributes
items[].source_refs + sources[]
safety
limitations
data_revision
cursor는 해석하거나 직접 생성하지 않고 retrieval.next_cursor 값을 그대로 사용한다.
query가 바뀌거나 새 release가 게시되면 cursor를 버리고 첫 페이지부터 조회한다.
7. Procedure Hub 자체 화면¶
{frontend-host}/knowledge-retrieval 화면만 같은 origin의 Next BFF를 호출한다.
POST {frontend-host}/api/v1/knowledge/retrieve
-> POST {backend-host}/procedure-hub/api/v1/knowledge/retrieve
다른 Backend 서비스는 Next BFF를 거치지 않고 Backend endpoint를 직접 호출한다.
8. 참고¶
한 요청 안의 실행 순서¶
현재 CanonicalRetrievalService.retrieve는 게시 release 확인 → entity 후보 조회·해석 →
검색 unit 조회 → 필요한 안전 규칙 조회 → 검증 근거 조회 → 정렬·페이지 구성 →
검색 영역·출처 조회 순서로 실행한다. 각 DB 조회를 순서대로 await하며,
한 요청 안에서 여러 작업을 gather로 병렬 실행하는 구조는 아니다.
비동기 API라는 것은 다른 요청과 I/O 대기를 겹칠 수 있다는 의미다. 이 API 내부의 조회 순서가 병렬이라는 뜻은 아니다. LLM 답변 생성은 소비 서비스의 책임이며 그쪽 호출의 직렬·병렬 여부는 소비 서비스 구현을 확인해야 한다.
- Swagger: https://api-stg-csp.medisolveai.com/procedure-hub/api-docs
- API schema:
knowledge_retrieval.py - Retrieval 로직:
application.py