Agent 2.0 exdev 서버 배포 스택

- server-dev start/stop/deploy 및 Gitea push 자동 배포 - local-dev 로컬 개발 환경 Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-21 22:57:30 +09:00
commit 4b86b2a660
344 changed files with 45787 additions and 0 deletions
@@ -0,0 +1,79 @@
+# RAG 기반 QA 챗봇
+
+엑셀 Q&A 데이터를 기반으로 동작하는 RAG(Retrieval Augmented Generation) 챗봇 API 서버입니다.
+
+---
+
+## 구조
+
+```
+qa_raw.jsonl → Embedding(게이트웨이) → Qdrant 벡터DB
+                                         ↕
+        FastAPI 서버 (api :28012, admin :28013)
+                                         ↕
+            모델 게이트웨이 (LLM / Embedding / Reranker, HTTPS)
+```
+
+- **벡터 스토어**: Qdrant 단일 구성 (FAISS 미사용). 벡터는 `./qdrant_data`에 영속.
+- **모델**: LLM·임베딩·리랭커를 통합 게이트웨이(HTTPS + Bearer 인증)로 호출.
+- **서비스**: `api`(Agent `/agent/chat`) + `admin`(벡터DB 큐레이션 검색/추가/수정/삭제).
+
+### Agent `/agent/chat`
+
+| 경로 | 오케스트레이션 | 설명 |
+|------|----------------|------|
+| `POST /agent/chat` | RAG `AgentService`가 **LLM tool loop** 로 자체 오케스트레이션 | `rag_search`·domain tool·`ask_user`를 스스로 선택. 환각/일관성 안전망(강제 rag·guidance·도메인 가드·검색어 맥락화·clarify 이력) 포함 |
+
+최종 문장은 `PromptBuilder`로 생성해 Admin·Web·Agent 답변을 일관되게 유지합니다. Agent 상세: [`../docs/AGENT_ARCHITECTURE.md`](../docs/AGENT_ARCHITECTURE.md) · 프롬프트: [`../docs/PROMPTS.md`](../docs/PROMPTS.md).
+
+---
+
+## 문서
+
+| 파일 | 설명 |
+|------|------|
+| `PROCESS_FLOW.md` | 전체 프로세스 흐름 (qa_raw.jsonl → Qdrant → 질문 처리) |
+| `DOCKER_COMMANDS.md` | Docker 실행·재기동·트러블슈팅 (Qdrant 기준) |
+| `VECTORDB_ADMIN_API.md` | 큐레이션 어드민 API 명세 (웹 개발자용) |
+| `env.template` | 환경변수 설정 템플릿 |
+
+---
+
+## 빠른 시작
+
+```bash
+# 1. 입력 데이터 배치 (q/a + source/source_id 권장)
+#    data/qa_raw.jsonl
+
+# 2. 환경설정
+cp env.template .env
+# .env 에서 MODEL_API_KEY(게이트웨이 키) 등 입력
+
+# 3. 실행 (qdrant → embed 적재 → api + admin)
+docker compose -f docker-compose-slim.yml up -d --no-build
+```
+
+자세한 내용은 `DOCKER_COMMANDS.md` 참고.
+
+---
+
+## API 엔드포인트
+
+```
+# 챗봇 (api, 28012)
+GET  /health      헬스체크
+POST /agent/chat  Agent tool-calling loop (Skill agent.mode=agent)
+
+# 큐레이션 어드민 (admin, 28013)
+GET  /                    웹 UI
+POST /api/search          의미 검색
+POST /api/keyword-search  문자열 포함 검색
+GET  /api/points          목록
+POST /api/points          추가   (PUT 수정 / DELETE 삭제)
+```
+
+```bash
+curl -X POST http://localhost:28012/agent/chat \
+  -H "Content-Type: application/json" \
+  -d '{"query": "질문 내용", "botId": "user-001"}'
+```