Passio RAG API 사용 설명서
이 페이지는 로그인 없이 누구나 열람할 수 있습니다. 실제 호출은 발급받은 API 토큰이 필요합니다.
1. 빠른 시작
가장 먼저 아래 한 줄을 실행하면 됩니다.
curl --max-time 1000 -X POST "https://sikdorak.org/api/rag/solve" \
-H "Content-Type: application/json" \
-H "X-API-Token: psk_xxxxxxxxxxxxxxxxxxxxxxxxx" \
-d '{
"items": [
{
"q": "네트워크관리사 2급: IPv4 주소 192.168.10.130/26이 속한 네트워크 주소는?",
"opts": "1) 192.168.10.0, 2) 192.168.10.64, 3) 192.168.10.128, 4) 192.168.10.192",
"wrong": "2) 192.168.10.64",
"ans": "3) 192.168.10.128"
}
],
"rebuild_db": false
}'2. 엔드포인트 정보
| Method | POST |
|---|---|
| URL | https://sikdorak.org/api/rag/solve |
| Content-Type | application/json |
| 인증 | X-API-Token 또는 로그인 세션 |
| 요청 제한 | 한 번에 최대 50문항 |
| 서버 대기시간 | 최대 900초 (15분) |
3. API 토큰 발급 방법
- Passio 웹 로그인 후 상단 메뉴에서 API 토큰 페이지로 이동
- 비밀번호를 한 번 더 입력하고 토큰 조회 버튼 클릭
- 조회된 토큰을 복사해 API 요청 헤더에 넣어 사용
보안 정책: API 토큰은 30일 유효, 만료 시 다음 조회 시점에 새 토큰으로 자동 갱신됩니다.
4. 요청 바디 스키마
{
"items": [
{
"q": "문제 본문 (필수)",
"opts": "보기 문자열 (필수)",
"wrong": "사용자가 고른 오답 (필수)",
"ans": "정답 (필수)"
}
],
"rebuild_db": false
}| 필드 | 타입 | 설명 |
|---|---|---|
| items | array | 풀이할 문항 목록 |
| items[].q | string | 문제 질문 |
| items[].opts | string | 보기(예: 1) ... 2) ...) |
| items[].wrong | string | 오답 선택값 |
| items[].ans | string | 정답 선택값 |
| rebuild_db | boolean | RAG DB 재생성 여부 (기본 false 권장) |
5. 인증 방식
아래 세 가지 중 하나를 사용하세요.
# 1) 권장: API 토큰
-H "X-API-Token: psk_xxx"
# 2) 대체: Authorization ApiKey
-H "Authorization: ApiKey psk_xxx"
# 3) 대체: Authorization Bearer (psk_ 토큰)
-H "Authorization: Bearer psk_xxx"6. 응답 예시
{
"ok": true,
"total": 1,
"results": [
{
"report": {
"header": {
"ans": "3) 192.168.10.128",
"keyword": "IPv4, 서브넷, /26",
"level": "중급"
},
"body": {
"overview": "...",
"analysis": {
"1": "...",
"2": "..."
},
"correction": "...",
"insight": "...",
"audit": {
"evidence_ids": ["1", "2"],
"source": "교재 근거"
},
"magic_tip": "..."
}
},
"evidence": [
{ "id": 1, "text": "..." }
]
}
]
}7. 에러 코드 가이드
| Status | error | 의미 |
|---|---|---|
| 400 | invalid_input | 요청 바디 형식 오류 또는 items 누락 |
| 401 | invalid_api_token | API 토큰이 잘못되었거나 만료됨 |
| 401 | unauthorized | 세션/토큰 인증 미제공 |
| 502 | rag_unavailable | 내부 RAG 서비스 연결 실패 |
| 504 | - | 게이트웨이 타임아웃(네트워크/처리 지연) |
8. 운영 팁
- 기본적으로 rebuild_db는 false를 사용하세요.
- 문항은 여러 개를 묶어 보내되, 50개를 넘기지 마세요.
- 클라이언트에서 1000초 이상 max-time을 설정해두면 장문 응답에 유리합니다.
- 토큰은 서버에 하드코딩하지 말고 환경변수/시크릿 스토어에 보관하세요.