목차 15개 섹션
- 기술 가이드
- 개발환경 구축
- AI Model 선정
- 모델 설치와 실행
- 학습과 튜닝
- Vector DB 구축
- RAG 개발
- 시스템 연계
- 검증과 운영
- 분야별 모델 선정
- 전체 아키텍처
- Project ABC
- 데이터와 도구
- 마일스톤/산출물
- 기술 스택
Technical Blueprint
실전 AI Agent 개발 체크리스트
아이디어 설명보다 실행 가능한 개발 문서를 우선합니다. 로컬 실행, API 계약, RAG 데이터, tool 호출, 검증 루틴, 운영 fallback을 먼저 고정해야 AI Agent가 데모에서 실제 서비스로 넘어갈 수 있습니다.
1. 개발환경과 실행 기준
- README 첫 화면에 `npm install`, `docker compose up`, `npm run build`, health check 명령을 순서대로 적습니다.
- Node.js 22 LTS, Python 3.11 이상, Git, Docker Desktop, VS Code 또는 Cursor를 기본 개발환경으로 고정합니다.
- 프론트엔드는 Next.js, Agent API는 FastAPI 또는 Cloudflare Worker, Vector DB는 Chroma 또는 pgvector 중 하나로 시작합니다.
- `.env.example`에는 모델명, API key, DB URL, vector collection, timeout, observability endpoint를 실제 변수명으로 남깁니다.
- 첫 커밋부터 build, API 단위 테스트, 대표 curl, k6 smoke test를 통과 기준으로 둡니다.
2. 모델과 비용 기준
- 업무를 대화, 문서 질의응답, 코드 생성, 데이터 분석, tool calling 중 하나로 먼저 분류합니다.
- 운영 후보 모델은 품질만 보지 말고 월 비용, p95 latency, JSON schema 준수율, 장애 fallback 가능성을 함께 비교합니다.
- 로컬 우선 프로젝트는 `llama3.1:8b`, `llama3.2:3b`, `gemma2:9b`, `nomic-embed-text`처럼 실제 설치할 모델명과 예상 용량을 문서에 적습니다.
- API 모델을 병행할 경우 provider adapter를 두고 `MODEL_PROVIDER`, `MODEL_NAME`, `MODEL_TIMEOUT_SECONDS`로 전환 가능하게 만듭니다.
- 모델 평가는 대표 질문 30~50개 golden set으로 정확성, 근거성, 환각률, 응답 지연, 실패 유형을 표로 남깁니다.
3. API 계약과 로컬 실행
- 처음 고정할 endpoint는 `/health`, `/v1/chat`, `/v1/rag/query`, `/v1/agent/run` 네 가지로 충분합니다.
- 모든 응답에는 `answer`, `citations`, `model`, `latency_ms`, `trace_id`, `warnings`를 같은 형태로 반환합니다.
- 브라우저는 모델 provider나 노트북 API를 직접 호출하지 않고, 서버 사이드 API facade만 호출하게 설계합니다.
- 로컬 모델은 Ollama 또는 Docker Compose로 실행하고, 모델 목록 조회와 첫 chat completion curl을 문서에 포함합니다.
- timeout, retry, max tokens, temperature, streaming 여부는 코드에 박지 말고 환경 변수로 분리합니다.
4. 프롬프트와 응답 정책
- system prompt에는 역할, 금지 행동, 근거 부족 시 답변 방식, tool 사용 조건을 짧게 고정합니다.
- 초기에는 fine-tuning보다 prompt template, RAG 문서 품질, tool schema, JSON 응답 형식을 먼저 개선합니다.
- 금지 답변, 근거 부족 답변, 사용자 확인이 필요한 답변 예시를 golden set에 포함합니다.
- 업무별 출력은 자유 문장이 아니라 `summary`, `evidence`, `next_actions`, `confidence`, `needs_review` 같은 schema로 관리합니다.
- 프롬프트 변경 시 golden set 통과율과 실패 유형을 이전 버전과 비교합니다.
5. RAG 데이터 구축
- 문서 원본, chunk, embedding, metadata, ingestion version을 분리해 저장하고 재색인 명령을 README에 적습니다.
- 처음에는 문서 10개로 시작해 chunk 크기, overlap, metadata, 검색 결과를 눈으로 확인합니다.
- 검색 API는 `query`, `top_k`, `filters`, `min_score`를 명시하고 source id, title, page, score, chunk text를 반환합니다.
- RAG 답변에는 citation을 필수로 두고, citation이 없으면 “근거 부족” 응답으로 fallback합니다.
- 문서 변경 감지, 증분 색인, 삭제 문서 tombstone, embedding version 변경 시 재색인 기준을 미리 정합니다.
6. Agent workflow 구현
- workflow는 intent 분류, retrieval 필요 여부 판단, tool 호출, 답변 생성, 검증, fallback 순서로 나눕니다.
- LangGraph를 쓰는 경우 각 node의 입력/출력 schema와 실패 시 다음 node를 문서화합니다.
- Agent가 호출할 tool은 읽기 전용부터 시작하고, 쓰기 작업은 사람 승인 단계 뒤에 둡니다.
- tool 호출에는 timeout, retry, rate limit, audit log, user permission check를 기본으로 붙입니다.
- 최종 답변은 근거, 다음 행동, 확인 필요 여부를 분리해 UI가 그대로 렌더링할 수 있게 반환합니다.
7. 시스템 연계와 보안
- Agent는 DB를 직접 조회하지 않고 `stock_search`, `portfolio_summary`, `log_search`, `policy_check` 같은 제한된 tool API만 호출합니다.
- 외부 API와 내부 DB adapter에는 권한, rate limit, timeout, retry, 감사 로그를 기본으로 둡니다.
- API key, JWT, session id, user id, request id의 책임 위치를 클라우드와 로컬 API 사이에서 명확히 나눕니다.
- 민감 정보는 prompt와 로그에 그대로 남기지 않고 masking 또는 별도 secure store로 분리합니다.
- 사용자 요청, tool 호출, 모델 응답, 최종 답변은 trace id로 연결해 장애 분석과 품질 개선에 활용합니다.
8. 검증과 운영 전환
- Golden set으로 정답성, 근거성, 정책 위반, 출력 형식 준수율을 측정하고 변경 전후 결과를 비교합니다.
- 운영 전 최소 기준은 health check, smoke test, k6 p95 latency, API error rate, RAG hit rate, fallback rate입니다.
- 금융/교육/운영 자동화처럼 위험도가 높은 영역은 LLM 판단과 deterministic rule 검사를 반드시 분리합니다.
- OpenTelemetry, Prometheus, Grafana 또는 최소 structured log로 latency, token usage, tool failure, retrieval hit rate를 관측합니다.
- 초기 배포는 읽기 전용 Agent와 사람 승인 기반 workflow로 시작하고, 충분한 검증 후 자동 실행 범위를 넓힙니다.
Model Selection
분야별 AI 모델 선정과 설치/활용
AI Ops 프로젝트에서 바로 POC를 시작할 수 있도록 추천 API 모델, 로컬 모델, 임베딩 모델과 설치/활용 기준을 정리합니다.
추천 API 모델
GPT-4.1 mini 또는 Gemini 2.5 Flash
로컬/온프레미스 대안
Llama 3.3 70B Instruct 또는 DeepSeek/Qwen coder 계열
Embedding 모델
text-embedding-3-large 또는 bge-m3
실제 선택 모델과 Docker 설치 기준
Qwen3-32B-Instruct를 AIOps AI Agent 기본 로컬 모델로 선택합니다. 로그/메트릭/런북 요약과 tool calling 흐름을 균형 있게 처리하고, 필요 시 coder 모델을 보조로 붙입니다.
초기에는 vLLM Docker로 OpenAI-compatible endpoint를 만들고, Prometheus/Loki/GitHub Actions adapter는 read-only token으로만 연결합니다.
권장 서버 스펙
- 개발/데모: GPU 24GB VRAM, RAM 64GB, NVMe SSD. 최근 로그와 런북 검색을 포함한 단일 사용자 진단에 적합합니다.
- 운영 POC: L40S 48GB 또는 A100 80GB 1장 이상. 장애 시 burst 요청과 긴 로그 요약을 고려합니다.
- 로그 ingestion과 모델 추론을 같은 서버에 몰지 말고, 최소 2개 컨테이너로 분리합니다.
용량과 저장소
- Qwen3 32B Q4 모델 약 18~24GB, FP16 캐시는 65GB 이상, 로그 샘플과 vector index 포함 최소 150GB SSD를 권장합니다.
- Prometheus/Loki 원본은 외부 시스템에 두고 AI Agent DB에는 incident snapshot, runbook chunk, 평가 결과만 저장합니다.
- 장애 재현용 로그는 7~30일 보관 정책을 두고 민감 토큰은 ingestion 전에 마스킹합니다.
Docker 설치 명령
- vLLM: `docker run --runtime nvidia --gpus all -v ~/.cache/huggingface:/root/.cache/huggingface -p 8000:8000 --ipc=host vllm/vllm-openai:latest --model Qwen/Qwen3-32B --max-model-len 32768`
- 로컬 빠른 검증: `docker run -d --gpus=all -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama` 후 `docker exec -it ollama ollama pull qwen3:32b`
- 앱 설정: `LLM_BASE_URL=http://localhost:8000/v1`, `LLM_MODEL=Qwen/Qwen3-32B`, `MODEL_TIMEOUT_SECONDS=30`
설치 후 검증
- 장애 알림 10개, 로그 묶음 10개, 런북 10개로 원인 후보와 근거 로그 매칭률을 측정합니다.
- 재시작, 삭제, 롤백, 스케일 변경 같은 write action은 모델 답변이 아니라 승인 workflow로만 노출되는지 확인합니다.
- p95 응답시간, tool failure rate, hallucinated service name 비율을 관측 지표로 둡니다.
선정 이유
- AI Ops Agent는 로그, 메트릭, 배포 이력, 런북을 종합해야 하므로 tool calling 안정성과 긴 컨텍스트 요약 능력이 중요합니다.
- 코드/스택트레이스 해석이 필요한 경우 coder 계열 로컬 모델을 보조 모델로 붙이면 원인 후보 설명 품질이 좋아집니다.
- 자동 복구보다 먼저 읽기 전용 진단과 사람 승인 기반 제안 모드로 시작하는 것이 안전합니다.
설치와 구성
- API형은 `LLM_MODEL=gpt-4.1-mini`, `FAST_MODEL=gpt-4.1-nano`로 원인 요약과 짧은 알림 분류를 분리합니다.
- 로컬형은 vLLM/Ollama endpoint를 FastAPI adapter 뒤에 두고 Prometheus, Loki, 배포 이력 API는 read-only token으로 연결합니다.
- 런북은 제목, 서비스명, severity, 증상, 복구 단계, 금지 명령 metadata를 포함해 Vector DB에 저장합니다.
활용 방식
- `metric_query`, `log_search`, `deploy_lookup`, `runbook_retriever`를 순서대로 호출해 원인 후보와 근거를 모읍니다.
- 모델 출력은 `incident_summary`, `likely_causes`, `evidence`, `recommended_runbook`, `requires_human_approval`로 고정합니다.
- 복구 명령 실행은 AI Agent 범위에서 제외하고 승인 UI와 감사 로그를 먼저 구현합니다.
주의점
- 삭제, 재시작, 스케일 변경, 배포 롤백 같은 명령은 모델이 직접 실행하지 않게 합니다.
- 런북 근거가 없으면 추측성 복구 절차를 생성하지 않도록 fallback 답변을 둡니다.
Reference Architecture
전체 아키텍처 설계
AI Agent는 화면, 오케스트레이션, 도구 연계, 데이터 검색, 평가/운영 계층을 분리해야 변경과 검증이 쉬워집니다.
Presentation Layer
- Next.js UI
- Agent 실행 상태
- 근거/출처 표시
- 사용자 피드백 수집
Agent Orchestration
- Prompt policy
- Tool routing
- Memory/session
- Structured output
Tool & Integration
- 업무 API adapter
- DB 조회 tool
- 문서 검색 tool
- 정책 검사 tool
Data & Retrieval
- PostgreSQL
- pgvector
- 문서 chunking
- embedding/reranking
Evaluation & Ops
- Golden set
- Playwright
- k6
- OpenTelemetry/Prometheus
Project ABC
실제 프로젝트 진행을 위한 ABC
A는 구조 설계, B는 AI Agent 구현, C는 검증 기준입니다. 이 순서로 진행하면 데모가 아니라 운영 가능한 Agent로 확장하기 쉽습니다.
A. Architecture
- 메트릭 조회, 로그 검색, 배포 이력 조회, 런북 검색을 읽기 전용 도구로 먼저 시작합니다.
- 복구 명령 실행은 AI Agent에서 제외하고 승인 기반 제안 모드로 설계합니다.
- Agent 상태는 알림 접수, 원인 후보, 근거 수집, 런북 추천, 사람 승인 단계로 나눕니다.
B. Build
- 샘플 장애 10개와 대응 런북 10개를 만들어 metric/log/runbook 연결 관계를 정의합니다.
- Prometheus query와 로그 검색은 시간 범위, 서비스명, severity를 필수 파라미터로 둡니다.
- 운영 UI는 알림 카드, 근거 로그, 메트릭 스냅샷, 추천 런북 순서로 구성합니다.
C. Check
- 잘못된 서비스명, 과도한 시간 범위, 권한 없는 도구 호출을 실패 케이스로 테스트합니다.
- 런북 없는 장애에서 추측성 복구 절차를 만들지 않는지 확인합니다.
- MTTR, 원인 후보 정확도, 런북 추천 정확도, p95 응답 시간을 핵심 지표로 봅니다.
Project Spec
데이터와 Agent 도구
데이터
- Prometheus metrics
- 애플리케이션 로그
- 배포 이력
- 장애 대응 런북
Agent Tools
metric_querylog_searchdeploy_lookuprunbook_retriever
AI Agent 범위
- 알림 원인 후보 정리
- 최근 배포 영향 확인
- 관련 로그 요약
- 복구 절차 제안
검증 기준
- 잘못된 명령 실행 차단
- 런북 근거 포함
- MTTR 단축 효과
- 권한별 도구 제한
Execution
진행 마일스톤과 산출물
진행 마일스톤
- 장애 샘플 설계
- 메트릭/로그 도구 구현
- 런북 검색 연결
- 승인 기반 UI
- 운영 안전성 검증
산출물
- AIOps Agent API
- 샘플 런북 세트
- Prometheus 쿼리 템플릿
- 운영 대시보드
- 안전 정책 테스트
Stack
기술 스택
FastAPIPrometheusGrafanaOpenTelemetryLangGraphk6