AutoTrading AI Investment Agent | AI Agent

목차 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로 시작하고, 충분한 검증 후 자동 실행 범위를 넓힙니다.

실시간 작동 데모

AI 스크린 랭킹 & Antigravity 연동 대시보드

설계도 블루프린트에 작성된 로컬 SQLite 데이터 동기화 및 pgvector 시맨틱 검색 기능을 가상 시뮬레이션으로 구현한 웹 데모입니다. 탑 랭킹 종목을 실시간으로 확인하고, Antigravity AI Agent의 multi-agent 추론 분석 프로세스를 즉시 확인해보세요.

작동 데모 실행하기 →

Model Selection

분야별 AI 모델 선정과 설치/활용

Finance 프로젝트에서 바로 POC를 시작할 수 있도록 추천 API 모델, 로컬 모델, 임베딩 모델과 설치/활용 기준을 정리합니다.

로컬/온프레미스 대안

qwen2.5:3b (한국어 지시 이행력 우수) 또는 gemma2:2b (초고속 추론)

Embedding 모델

nomic-embed-text (768차원 고성능 텍스트 임베딩)

실제 선택 모델과 Docker 설치 기준

16GB RAM 일반 노트북/PC 환경에서 메모리 고갈(OOM) 없이 원활한 CPU 추론이 가능하도록 qwen2.5:3b 모델을 기본으로 채택합니다. 속도 중시 및 극소 가용 메모리 환경을 위해 gemma2:2b 모델도 함께 다운로드받아 상시 교체 가능하게 지원합니다.

모든 서비스는 Docker Compose 환경에서 관리합니다. aia_postgres 컨테이너는 pgvector가 포함된 PostgreSQL 16 버전을 사용하고, aia_ollama는 로컬 LLM 추론 엔진 역할을 담당하며, aia_backend는 FastAPI 웹 애플리케이션으로 동작합니다.

권장 서버 스펙

최소: RAM 16GB, SSD 여유 공간 20GB 이상, 4코어 이상 CPU (Intel Arc GPU 및 WSL2 CPU 가속 대응)
권장: RAM 32GB 이상 (동시 요청 시 더 안정적인 CPU 추론 속도 보장)
주의: 16GB RAM 환경의 경우 WSL2 가상머신에 최소 8GB~12GB 이상 메모리 할당이 필요하며, 사용하지 않는 호스트 브라우저 창 등을 종료해 물리 OOM을 예방합니다.

용량과 저장소

Ollama core 런타임: 약 1.5 GB
qwen2.5:3b 모델 파일: 약 1.9 GB
gemma2:2b 모델 파일: 약 1.6 GB
nomic-embed-text 임베딩 모델: 약 274 MB
PostgreSQL pgvector 및 SQLite 데이터 볼륨: 약 5GB 미만

Docker 설치 명령

프로젝트 루트에 docker-compose.yml을 작성하여 postgres, ollama, backend 서비스를 정의합니다.
Postgres 외부 포트는 5435(내부 5432)로 포워딩하여 로컬 클라이언트 연동 편의를 돕고, backend는 8000번 포트를 바인딩합니다.
컨테이너 기동: `docker-compose up -d --build`로 스택을 한 번에 빌드하고 실행합니다.
Ollama 모델 풀링: `docker exec -it aia_ollama ollama pull qwen2.5:3b` 및 `docker exec -it aia_ollama ollama pull nomic-embed-text` 명령을 수행합니다.

설치 후 검증

Ollama 모델 목록 검증: `docker exec aia_ollama ollama list`를 실행하여 모델이 정상 로드되었는지 확인합니다.
컨테이너 프로세스 검증: `docker ps` 명령어로 3대 컨테이너가 정상 구동(Up) 중인지 체크합니다.
가상환경 통합 검증: 로컬 가상환경(.venv)을 활성화한 뒤 `$env:PYTHONIOENCODING="utf-8"; python -m backend.test_integration` 실행 결과 한글 리포트가 정상 요약/임베딩되는지 확인합니다.

선정 이유

기존 AutoTrading 시스템의 정량적 점수 데이터와 yfinance의 주가 지표 데이터를 결합해 질적인 투자 포인트(리포트)로 합성하려면, 자연어 요약과 임베딩 생성 파이프라인이 필수적입니다.
로컬 CPU 단일 PC 환경에서 구동하기 위해 llama-70B와 같은 대형 모델 대신 다국어 성능이 우수하고 크기가 작아 가벼운 qwen2.5:3b를 적용하여 지연 시간을 획기적으로 줄였습니다.
PostgreSQL pgvector 확장 모듈을 활용하면, 주식 리포트의 텍스트 조각을 벡터화해 저장한 뒤 사용자의 질문과 가장 연관성이 깊은 데이터를 밀리초 단위로 검색(RAG)해 낼 수 있어 에이전트 브레인에 지식을 이식하기 좋습니다.
yfinance API를 Agent의 명시적인 Tool로 결합함으로써, LLM이 최근 주가 상태나 재무제표를 허위로 답변하지 못하도록 실제 데이터를 참조하는 안전 장치를 제공합니다.

설치와 구성

1. 프로젝트 루트에 .env 파일을 생성하고 DATABASE_URL(postgres:5435), OLLAMA_BASE_URL(http://localhost:11434), LLM_MODEL_NAME(qwen2.5:3b), EMBEDDING_MODEL_NAME(nomic-embed-text)을 설정합니다.
2. docker-compose.yml을 작성하여 pgvector postgres 컨테이너(포트 5435), ollama 컨테이너(포트 11434), FastAPI backend 컨테이너(포트 8000)를 연결합니다.
3. backend/db.py에 SQLAlchemy와 pgvector DDL(ScreenerReport 모델)을 매핑하고, backend/autotrading_connector.py에 SQLite 연결 유틸을 구현합니다.
4. backend/agent/screener_synthesizer.py에 qwen2.5:3b 기반 리포트 요약 함수 및 nomic-embed-text 임베딩 유틸을 작성합니다.
5. backend/agent/tools.py에 yfinance 파이낸셜 API와 pgvector 시맨틱 검색 함수를 LangChain @tool 데코레이터로 바인딩합니다.

활용 방식

1. 데이터 동기화 API 호출 (SQLite ➡️ AI 요약 ➡️ pgvector 적재):
`Invoke-RestMethod -Uri "http://localhost:8000/api/autotrading/sync?limit=3" -Method Post`
2. 자연어 시맨틱 벡터 검색 API 호출:
`$body = @{ query = "수급이 좋고 상승 흐름을 타는 종목 추천해줘"; limit = 2 } | ConvertTo-Json`
`Invoke-RestMethod -Uri "http://localhost:8000/api/autotrading/search" -Method Post -ContentType "application/json" -Body $body`
3. AI 투자 에이전트 대화 API 호출 (yfinance / RAG Tool 자동 매핑):
`$body = @{ prompt = "스크리너 보고서 검색 도구를 사용하여 한화에어로스페이스의 투자 포인트를 알려줘" } | ConvertTo-Json`
`Invoke-RestMethod -Uri "http://localhost:8000/api/chat" -Method Post -ContentType "application/json" -Body $body`

주의점

로컬 CPU로 구동되므로 다량의 데이터를 한 번에 동기화할 경우(/api/autotrading/sync) 응답 지연이 발생합니다. limit 쿼리 파라미터를 사용해 소량씩 순차적으로 실행할 것을 권장합니다.
한국 주식 티커의 경우 야후 파이낸스 포맷(예: 삼성전자 -> 005930.KS)으로 정확히 치환하여 툴에 전달해야 하므로, 에이전트 프롬프트 템플릿에 명확한 Ticker 규칙을 작성해 주어야 합니다.
Docker 컨테이너 간의 통신 시에는 `localhost` 대신 컨테이너 네트워크 호스트명(예: `http://ollama:11434`)을 사용하여 호스트-컨테이너 간의 포트 맵 문제를 방지합니다.

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

SQLite DB 커넥터 계층: AutoTrading의 스크리너 랭킹 및 세부 점수(145점 만점 기준)를 고속 추출하는 모듈 설계.
AI Synthesizer 계층: Qwen 2.5 3B 프롬프트 템플릿을 통과시켜 계량 수치를 전문 투자 분석 리포트 문서(한글)로 합성.
RAG & Vector DB 계층: nomic-embed-text로 보고서 임베딩 벡터를 뽑아 Docker pgvector DB에 적재 및 코사인 유사도 검색 구현.
LangChain ReAct Agent 계층: yfinance API 도구와 pgvector 검색 도구를 결합하여, 질문 분류 및 도구 탐색-실행-답변 루프 통제.

B. Build

FastAPI main.py 서버를 구현하고 Startup 이벤트 핸들러에서 pgvector 데이터베이스 및 테이블 스키마 초기화 로직 구현.
langchain_classic의 create_react_agent 및 AgentExecutor를 사용하여 Classic-Classic 버전 간 임포트 에러를 방지한 AI 에이전트 초기화.
docker-compose up -d --build 명령어로 PostgreSQL, Ollama, FastAPI 서버 인프라를 로컬 컨테이너 네트워크에 묶어 기동.

C. Check

PowerShell에서 UTF-8 인코딩 환경변수를 사용하여 test_integration.py 스크립트 실행 시 한글 리포트가 정상 생성되는지 검증.
API `/api/autotrading/sync`를 트리거하여 top-3 종목이 누락 없이 pgvector에 정상 적재되는지 검사.
API `/api/chat`에 "한화에어로스페이스 투자 포인트"를 입력했을 때 에이전트가 `search_screener_reports` 도구를 정상적으로 타서 정답을 도출하는지 최종 확인.

Project Spec

데이터와 Agent 도구

데이터

AutoTrading SQLite 스크리너 결과 (autotrading.db)
AI 합성 종목 요약 보고서
768차원 임베딩 벡터
yfinance 실시간 주가/재무 정보

Agent Tools

get_stock_financials
get_stock_price_history
search_screener_reports
get_latest_top_screener_stocks
analyze_user_portfolio

AI Agent 범위

SQLite 스크리너 DB 커넥터 개발
Ollama 로컬 요약 및 임베딩 파이프라인 구축
FastAPI 데이터 동기화(/api/autotrading/sync) 구현
pgvector 기반 자연어 검색(/api/autotrading/search) 구현
LangChain ReAct 투자 AI 에이전트 및 Chat API(/api/chat) 연동

검증 기준

SQLite 데이터 정상 추출 여부
Qwen 2.5 3B 요약 및 nomic-embed-text 벡터화 성공 여부
pgvector 유사도 검색(Cosine Distance) 정확도
에이전트의 상황별 적절한 도구(Tool) 선택 및 한국어 최종 답변 품질

Execution

진행 마일스톤과 산출물

진행 마일스톤

SQLite 스크리너 DB 커넥터 구현
Docker Compose 로컬 인프라(pgvector/Ollama) 구성 및 기동
Qwen 2.5 3B 및 nomic-embed-text 모델 풀링
FastAPI 동기화 및 자연어 검색 API 설계
LangChain 기반 yfinance / pgvector RAG 에이전트 연동
로컬 통합 스크립트 동작 유효성 검증
FastAPI 엔드포인트 동작 curl 테스트 완료

산출물

docker-compose.yml 및 Dockerfile 설정
FastAPI main.py 및 db.py 스크립트
agent/tools.py 및 agent/investment_agent.py 에이전트 코드
test_integration.py 연동 검증용 테스트 코드
SQLite autotrading.db 데이터 파일
AI Agent 실전 실행 가이드 (AIAgentRun.md)

Stack

기술 스택

FastAPIOllamaqwen2.5:3bnomic-embed-textPostgreSQLpgvectorSQLiteLangChain-ClassicyfinanceDocker Compose

목차 15개 섹션

기술 가이드
개발환경 구축
AI Model 선정
모델 설치와 실행
학습과 튜닝
Vector DB 구축
RAG 개발
시스템 연계
검증과 운영
분야별 모델 선정
전체 아키텍처
Project ABC
데이터와 도구
마일스톤/산출물
기술 스택

Technical Blueprint

실전 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로 시작하고, 충분한 검증 후 자동 실행 범위를 넓힙니다.

실시간 작동 데모

AI 스크린 랭킹 & Antigravity 연동 대시보드

작동 데모 실행하기 →

Model Selection

분야별 AI 모델 선정과 설치/활용

Finance 프로젝트에서 바로 POC를 시작할 수 있도록 추천 API 모델, 로컬 모델, 임베딩 모델과 설치/활용 기준을 정리합니다.

로컬/온프레미스 대안

qwen2.5:3b (한국어 지시 이행력 우수) 또는 gemma2:2b (초고속 추론)

Embedding 모델

nomic-embed-text (768차원 고성능 텍스트 임베딩)

실제 선택 모델과 Docker 설치 기준

권장 서버 스펙

최소: RAM 16GB, SSD 여유 공간 20GB 이상, 4코어 이상 CPU (Intel Arc GPU 및 WSL2 CPU 가속 대응)
권장: RAM 32GB 이상 (동시 요청 시 더 안정적인 CPU 추론 속도 보장)
주의: 16GB RAM 환경의 경우 WSL2 가상머신에 최소 8GB~12GB 이상 메모리 할당이 필요하며, 사용하지 않는 호스트 브라우저 창 등을 종료해 물리 OOM을 예방합니다.

용량과 저장소

Ollama core 런타임: 약 1.5 GB
qwen2.5:3b 모델 파일: 약 1.9 GB
gemma2:2b 모델 파일: 약 1.6 GB
nomic-embed-text 임베딩 모델: 약 274 MB
PostgreSQL pgvector 및 SQLite 데이터 볼륨: 약 5GB 미만

Docker 설치 명령

프로젝트 루트에 docker-compose.yml을 작성하여 postgres, ollama, backend 서비스를 정의합니다.
Postgres 외부 포트는 5435(내부 5432)로 포워딩하여 로컬 클라이언트 연동 편의를 돕고, backend는 8000번 포트를 바인딩합니다.
컨테이너 기동: `docker-compose up -d --build`로 스택을 한 번에 빌드하고 실행합니다.
Ollama 모델 풀링: `docker exec -it aia_ollama ollama pull qwen2.5:3b` 및 `docker exec -it aia_ollama ollama pull nomic-embed-text` 명령을 수행합니다.

설치 후 검증

Ollama 모델 목록 검증: `docker exec aia_ollama ollama list`를 실행하여 모델이 정상 로드되었는지 확인합니다.
컨테이너 프로세스 검증: `docker ps` 명령어로 3대 컨테이너가 정상 구동(Up) 중인지 체크합니다.
가상환경 통합 검증: 로컬 가상환경(.venv)을 활성화한 뒤 `$env:PYTHONIOENCODING="utf-8"; python -m backend.test_integration` 실행 결과 한글 리포트가 정상 요약/임베딩되는지 확인합니다.

선정 이유

기존 AutoTrading 시스템의 정량적 점수 데이터와 yfinance의 주가 지표 데이터를 결합해 질적인 투자 포인트(리포트)로 합성하려면, 자연어 요약과 임베딩 생성 파이프라인이 필수적입니다.
로컬 CPU 단일 PC 환경에서 구동하기 위해 llama-70B와 같은 대형 모델 대신 다국어 성능이 우수하고 크기가 작아 가벼운 qwen2.5:3b를 적용하여 지연 시간을 획기적으로 줄였습니다.
PostgreSQL pgvector 확장 모듈을 활용하면, 주식 리포트의 텍스트 조각을 벡터화해 저장한 뒤 사용자의 질문과 가장 연관성이 깊은 데이터를 밀리초 단위로 검색(RAG)해 낼 수 있어 에이전트 브레인에 지식을 이식하기 좋습니다.
yfinance API를 Agent의 명시적인 Tool로 결합함으로써, LLM이 최근 주가 상태나 재무제표를 허위로 답변하지 못하도록 실제 데이터를 참조하는 안전 장치를 제공합니다.

설치와 구성

1. 프로젝트 루트에 .env 파일을 생성하고 DATABASE_URL(postgres:5435), OLLAMA_BASE_URL(http://localhost:11434), LLM_MODEL_NAME(qwen2.5:3b), EMBEDDING_MODEL_NAME(nomic-embed-text)을 설정합니다.
2. docker-compose.yml을 작성하여 pgvector postgres 컨테이너(포트 5435), ollama 컨테이너(포트 11434), FastAPI backend 컨테이너(포트 8000)를 연결합니다.
3. backend/db.py에 SQLAlchemy와 pgvector DDL(ScreenerReport 모델)을 매핑하고, backend/autotrading_connector.py에 SQLite 연결 유틸을 구현합니다.
4. backend/agent/screener_synthesizer.py에 qwen2.5:3b 기반 리포트 요약 함수 및 nomic-embed-text 임베딩 유틸을 작성합니다.
5. backend/agent/tools.py에 yfinance 파이낸셜 API와 pgvector 시맨틱 검색 함수를 LangChain @tool 데코레이터로 바인딩합니다.

활용 방식

1. 데이터 동기화 API 호출 (SQLite ➡️ AI 요약 ➡️ pgvector 적재):
`Invoke-RestMethod -Uri "http://localhost:8000/api/autotrading/sync?limit=3" -Method Post`
2. 자연어 시맨틱 벡터 검색 API 호출:
`$body = @{ query = "수급이 좋고 상승 흐름을 타는 종목 추천해줘"; limit = 2 } | ConvertTo-Json`
`Invoke-RestMethod -Uri "http://localhost:8000/api/autotrading/search" -Method Post -ContentType "application/json" -Body $body`
3. AI 투자 에이전트 대화 API 호출 (yfinance / RAG Tool 자동 매핑):
`$body = @{ prompt = "스크리너 보고서 검색 도구를 사용하여 한화에어로스페이스의 투자 포인트를 알려줘" } | ConvertTo-Json`
`Invoke-RestMethod -Uri "http://localhost:8000/api/chat" -Method Post -ContentType "application/json" -Body $body`

주의점

로컬 CPU로 구동되므로 다량의 데이터를 한 번에 동기화할 경우(/api/autotrading/sync) 응답 지연이 발생합니다. limit 쿼리 파라미터를 사용해 소량씩 순차적으로 실행할 것을 권장합니다.
한국 주식 티커의 경우 야후 파이낸스 포맷(예: 삼성전자 -> 005930.KS)으로 정확히 치환하여 툴에 전달해야 하므로, 에이전트 프롬프트 템플릿에 명확한 Ticker 규칙을 작성해 주어야 합니다.
Docker 컨테이너 간의 통신 시에는 `localhost` 대신 컨테이너 네트워크 호스트명(예: `http://ollama:11434`)을 사용하여 호스트-컨테이너 간의 포트 맵 문제를 방지합니다.

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

SQLite DB 커넥터 계층: AutoTrading의 스크리너 랭킹 및 세부 점수(145점 만점 기준)를 고속 추출하는 모듈 설계.
AI Synthesizer 계층: Qwen 2.5 3B 프롬프트 템플릿을 통과시켜 계량 수치를 전문 투자 분석 리포트 문서(한글)로 합성.
RAG & Vector DB 계층: nomic-embed-text로 보고서 임베딩 벡터를 뽑아 Docker pgvector DB에 적재 및 코사인 유사도 검색 구현.
LangChain ReAct Agent 계층: yfinance API 도구와 pgvector 검색 도구를 결합하여, 질문 분류 및 도구 탐색-실행-답변 루프 통제.

B. Build

FastAPI main.py 서버를 구현하고 Startup 이벤트 핸들러에서 pgvector 데이터베이스 및 테이블 스키마 초기화 로직 구현.
langchain_classic의 create_react_agent 및 AgentExecutor를 사용하여 Classic-Classic 버전 간 임포트 에러를 방지한 AI 에이전트 초기화.
docker-compose up -d --build 명령어로 PostgreSQL, Ollama, FastAPI 서버 인프라를 로컬 컨테이너 네트워크에 묶어 기동.

C. Check

PowerShell에서 UTF-8 인코딩 환경변수를 사용하여 test_integration.py 스크립트 실행 시 한글 리포트가 정상 생성되는지 검증.
API `/api/autotrading/sync`를 트리거하여 top-3 종목이 누락 없이 pgvector에 정상 적재되는지 검사.
API `/api/chat`에 "한화에어로스페이스 투자 포인트"를 입력했을 때 에이전트가 `search_screener_reports` 도구를 정상적으로 타서 정답을 도출하는지 최종 확인.

Project Spec

데이터와 Agent 도구

데이터

AutoTrading SQLite 스크리너 결과 (autotrading.db)
AI 합성 종목 요약 보고서
768차원 임베딩 벡터
yfinance 실시간 주가/재무 정보

Agent Tools

get_stock_financials
get_stock_price_history
search_screener_reports
get_latest_top_screener_stocks
analyze_user_portfolio

AI Agent 범위

SQLite 스크리너 DB 커넥터 개발
Ollama 로컬 요약 및 임베딩 파이프라인 구축
FastAPI 데이터 동기화(/api/autotrading/sync) 구현
pgvector 기반 자연어 검색(/api/autotrading/search) 구현
LangChain ReAct 투자 AI 에이전트 및 Chat API(/api/chat) 연동

검증 기준

SQLite 데이터 정상 추출 여부
Qwen 2.5 3B 요약 및 nomic-embed-text 벡터화 성공 여부
pgvector 유사도 검색(Cosine Distance) 정확도
에이전트의 상황별 적절한 도구(Tool) 선택 및 한국어 최종 답변 품질

Execution

진행 마일스톤과 산출물

진행 마일스톤

SQLite 스크리너 DB 커넥터 구현
Docker Compose 로컬 인프라(pgvector/Ollama) 구성 및 기동
Qwen 2.5 3B 및 nomic-embed-text 모델 풀링
FastAPI 동기화 및 자연어 검색 API 설계
LangChain 기반 yfinance / pgvector RAG 에이전트 연동
로컬 통합 스크립트 동작 유효성 검증
FastAPI 엔드포인트 동작 curl 테스트 완료

산출물

docker-compose.yml 및 Dockerfile 설정
FastAPI main.py 및 db.py 스크립트
agent/tools.py 및 agent/investment_agent.py 에이전트 코드
test_integration.py 연동 검증용 테스트 코드
SQLite autotrading.db 데이터 파일
AI Agent 실전 실행 가이드 (AIAgentRun.md)

Stack

기술 스택

FastAPIOllamaqwen2.5:3bnomic-embed-textPostgreSQLpgvectorSQLiteLangChain-ClassicyfinanceDocker Compose

FIN AutoTrading AI Investment Agent AI Agent 프로젝트

실전 AI Agent 개발 체크리스트

1. 개발환경과 실행 기준

2. 모델과 비용 기준

3. API 계약과 로컬 실행

4. 프롬프트와 응답 정책

5. RAG 데이터 구축

6. Agent workflow 구현

7. 시스템 연계와 보안

8. 검증과 운영 전환

AI 스크린 랭킹 & Antigravity 연동 대시보드

분야별 AI 모델 선정과 설치/활용

추천 API 모델

로컬/온프레미스 대안

Embedding 모델

실제 선택 모델과 Docker 설치 기준

권장 서버 스펙

용량과 저장소

Docker 설치 명령

설치 후 검증

선정 이유

설치와 구성

활용 방식

주의점

전체 아키텍처 설계

Presentation Layer

Agent Orchestration

Tool & Integration

Data & Retrieval

Evaluation & Ops

실제 프로젝트 진행을 위한 ABC

A. Architecture

B. Build

C. Check

데이터와 Agent 도구

데이터

Agent Tools

AI Agent 범위

검증 기준

진행 마일스톤과 산출물

진행 마일스톤

산출물

기술 스택

FIN AutoTrading AI Investment Agent AI Agent 프로젝트

실전 AI Agent 개발 체크리스트

1. 개발환경과 실행 기준

2. 모델과 비용 기준

3. API 계약과 로컬 실행

4. 프롬프트와 응답 정책

5. RAG 데이터 구축

6. Agent workflow 구현

7. 시스템 연계와 보안

8. 검증과 운영 전환

AI 스크린 랭킹 & Antigravity 연동 대시보드

분야별 AI 모델 선정과 설치/활용

추천 API 모델

로컬/온프레미스 대안

Embedding 모델

실제 선택 모델과 Docker 설치 기준

권장 서버 스펙

용량과 저장소

Docker 설치 명령

설치 후 검증

선정 이유

설치와 구성

활용 방식

주의점

전체 아키텍처 설계

Presentation Layer

Agent Orchestration

Tool & Integration

Data & Retrieval

Evaluation & Ops

실제 프로젝트 진행을 위한 ABC

A. Architecture

B. Build

C. Check

데이터와 Agent 도구

데이터

Agent Tools