API¶

RAG4U는 Streamlit UI 없이 API만으로도 사용할 수 있습니다.

기본 주소:

http://127.0.0.1:8010

자동 API 문서:

http://127.0.0.1:8010/docs

Health¶

curl http://127.0.0.1:8010/health

문서 색인¶

curl -X POST http://127.0.0.1:8010/documents \
  -H 'Content-Type: application/json' \
  -d '{
    "path": "data/samples/manual",
    "domain_profile": "manual",
    "recursive": true,
    "force": true
  }'

요청 필드:

필드	설명
`path`	파일 또는 폴더 경로
`domain_profile`	`general`, `manual`, `internal-policy` 등
`recursive`	하위 폴더까지 읽을지 여부
`force`	해시가 같아도 다시 색인할지 여부

문서 목록¶

curl http://127.0.0.1:8010/documents

문서 상태, 파일명, 해시, chunk 수, 실패 사유를 확인합니다.

질문¶

curl -X POST http://127.0.0.1:8010/query \
  -H 'Content-Type: application/json' \
  -d '{
    "question": "E37 오류는 무엇을 의미하나요?",
    "domain_profile": "manual",
    "provider": "mock",
    "top_k": 5,
    "allow_external_context": false,
    "enable_tools": false
  }'

응답에는 다음 정보가 포함됩니다.

answer_text
citations
confidence_label
retrieved_chunks
tool_calls
provider
model
latency_ms

Agentic DB Tools¶

provider="openai" 또는 provider="codex"에서 enable_tools=true를 보내면 DB tool을 선택 호출할 수 있습니다. OpenAI는 Responses API function calling을 사용하고, Codex는 tool 선택 JSON을 받은 뒤 앱이 DB tool을 실행하는 흐름을 사용합니다.

curl -X POST http://127.0.0.1:8010/query \
  -H 'Content-Type: application/json' \
  -d '{
    "question": "P-101 최근 알람과 정비 이력을 같이 요약해줘",
    "domain_profile": "general",
    "provider": "codex",
    "top_k": 5,
    "allow_external_context": true,
    "enable_tools": true
  }'

응답의 tool_calls에는 tool명, 인자, 상태, row 수, 미리보기, latency가 포함됩니다.

allow_external_context¶

openai와 codex provider는 검색된 문서 청크를 외부 provider로 보냅니다. enable_tools=true인 경우 DB tool 결과도 선택한 외부 provider로 전달됩니다. 이 경우 반드시 다음 값을 넣어야 합니다.

{
  "allow_external_context": true
}

동의가 없으면 API는 요청을 거절합니다.

Provider 목록¶

curl http://127.0.0.1:8010/providers

현재 사용 가능한 LLM provider와 임베딩 provider 설정을 반환합니다.

Tool 목록¶

curl http://127.0.0.1:8010/tools

사용 가능한 DB tool schema를 반환합니다.

Tool DB 상태¶

curl http://127.0.0.1:8010/tools/db/status

PostgreSQL 연결 여부와 데모 테이블 row count를 반환합니다.

Profile 목록¶

curl http://127.0.0.1:8010/profiles

Profile 추가 또는 수정¶

curl -X POST http://127.0.0.1:8010/profiles \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "hr-policy",
    "description": "HR policy search",
    "metadata": {
      "answer_style": {"format": "policy_summary"},
      "safety_policy": {"require_citation": true}
    }
  }'

평가 실행¶

curl -X POST http://127.0.0.1:8010/eval/run \
  -H 'Content-Type: application/json' \
  -d '{
    "path": "data/evaluation/evaluation_cases.jsonl",
    "top_k": 5
  }'

평가는 retrieval top-k 성공률과 abstention 성공률을 반환합니다.