Local Ollama 기반 Math/Bio 연구 보조 Agent입니다. Terminal chat과 Web chat을 모두 지원하며, Linux와 Windows 모두에서 Docker를 통해 실행할 수 있습니다.
| 항목 | Linux | Windows |
|---|---|---|
| Docker | Docker Engine + Compose plugin | Docker Desktop |
| Ollama | Host에 설치 | Host에 설치 |
| PowerShell | 불필요 | 5.1 이상 (Windows 기본 내장) |
ollama pull qwen3.5:9b
ollama pull qwen3.5:4b
ollama pull nomic-embed-textLinux에서는 docker-compose.agent.yml과 network_mode: host를 사용합니다.
컨테이너가 host 네트워크를 공유하므로 Ollama(localhost:11434)에 직접 접근합니다.
chmod +x run_chat_linux.sh
./run_chat_linux.sh테이블 출력 형식을 지정하려면 스크립트 내부 또는 아래 명령을 직접 실행합니다.
# 기본 (xlsx)
docker compose -f docker-compose.agent.yml run --rm agent python main.py chat
# 테이블 형식 지정 (xlsx / csv / tsv / png / pdf)
docker compose -f docker-compose.agent.yml run --rm agent python main.py chat --table-format csv파일 첨부 예시:
# DEG 테이블 첨부
docker compose -f docker-compose.agent.yml run --rm agent \
python main.py chat \
--question "이 DEG table을 padj 0.1 기준으로 해석해줘" \
--table data/user_inputs/deg.csv
# 이미지 첨부
docker compose -f docker-compose.agent.yml run --rm agent \
python main.py chat \
--question "이 FACS plot을 해석해줘" \
--image data/user_inputs/facs.pngchmod +x run_web_linux.sh
./run_web_linux.sh브라우저에서 접속:
http://localhost:8000
같은 네트워크의 다른 PC에서 접속하려면 서버 PC의 IP를 사용합니다.
http://<SERVER_PC_IP>:8000
Windows에서는 Docker Desktop이 내부 VM 위에서 동작하므로 network_mode: host를 사용할 수 없습니다.
대신 docker-compose.windows.yml을 사용하며, host.docker.internal을 통해 Windows host의 Ollama에 접근합니다.
① PowerShell 실행 정책 허용
PowerShell을 열고 아래 명령을 실행합니다.
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser② Ollama host 바인딩 설정
Docker 컨테이너에서 Windows host의 Ollama에 접근하려면 Ollama가 0.0.0.0에 바인딩되어야 합니다.
Windows 사용자 환경변수에 등록한 뒤 Ollama를 재시작합니다.
# 사용자 환경변수에 영구 등록
[System.Environment]::SetEnvironmentVariable("OLLAMA_HOST", "0.0.0.0", "User")설정 후 트레이의 Ollama 아이콘 → Quit 으로 종료하고 Ollama를 다시 실행하거나,
다음과 같이 PowerShell에서 직접 올립니다.
$env:OLLAMA_HOST = "0.0.0.0"
ollama serve설정 확인:
http://localhost:11434에 브라우저로 접속했을 때 응답이 오면 정상입니다.
PowerShell에서 프로젝트 디렉터리로 이동 후 실행합니다.
.\run_chat_windows.ps1테이블 출력 형식을 지정할 수 있습니다.
# 기본 (xlsx)
.\run_chat_windows.ps1
# 테이블 형식 지정 (xlsx / csv / tsv / png / pdf)
.\run_chat_windows.ps1 -TableFormat csv또는 직접 실행:
docker compose -f docker-compose.windows.yml run --rm agent python main.py chat
docker compose -f docker-compose.windows.yml run --rm agent python main.py chat --table-format csv파일 첨부 예시:
# DEG 테이블 첨부
docker compose -f docker-compose.windows.yml run --rm agent `
python main.py chat `
--question "이 DEG table을 padj 0.1 기준으로 해석해줘" `
--table data/user_inputs/deg.csv
# 이미지 첨부
docker compose -f docker-compose.windows.yml run --rm agent `
python main.py chat `
--question "이 FACS plot을 해석해줘" `
--image data/user_inputs/facs.png.\run_web_windows.ps1브라우저에서 접속:
http://localhost:8000
같은 네트워크의 다른 PC에서 접속하려면 Windows PC의 IP를 사용합니다.
http://<WINDOWS_PC_IP>:8000
Windows 방화벽에서 8000번 포트를 허용해야 다른 기기에서 접속할 수 있습니다.
| 항목 | Linux | Windows |
|---|---|---|
| Compose 파일 | docker-compose.agent.yml |
docker-compose.windows.yml |
| 실행 스크립트 | run_*.sh (bash) |
run_*.ps1 (PowerShell) |
| 네트워크 모드 | network_mode: host |
bridge (기본값) |
| Ollama 접근 URL | http://localhost:11434 |
http://host.docker.internal:11434 |
| 포트 노출 방식 | host 공유 (자동) | ports: - "8000:8000" 명시 |
| Ollama 바인딩 설정 | 불필요 | OLLAMA_HOST=0.0.0.0 필요 |
- 실시간 스트리밍: 답변이 생성되는 동안 화면 하단에 진행 상태가 표시됩니다.
- Markdown 렌더링: 코드 블록, 표, 제목 등이 서식에 맞게 출력됩니다.
- 테이블 다운로드: 답변에 포함된 표는 CSV 파일로 다운로드할 수 있습니다.
- 다이어그램 다운로드: Mermaid 다이어그램은 SVG 파일로 다운로드할 수 있습니다.
- 파일 첨부: 질문 시 표(CSV/XLSX) 또는 이미지를 함께 업로드할 수 있습니다.
- 채팅 관리: 사이드바의
⋯버튼으로 채팅 이름 변경 및 삭제가 가능합니다.
/register에서 계정을 생성합니다.- 계정명은 중복될 수 없습니다.
- 로그인 후 왼쪽 사이드바에서 이전 채팅을 볼 수 있습니다.
- 채팅 기록은 서버 PC의 SQLite DB에 저장됩니다.
- DB 기본 위치:
data/web_app.sqlite3 - 업로드 파일 기본 위치:
data/web_uploads/
LAN 내부 사용을 우선 가정합니다. 외부에 공개하려면 최소한 다음을 설정하세요.
- 강한
WEB_SESSION_SECRET(스크립트 실행 전 환경변수로 지정) - 방화벽 또는 reverse proxy 인증
- HTTPS
- 파일 업로드 크기 제한 (
config.yaml→web.max_upload_mb) - 사용자별 rate limit
- Ollama는 외부 네트워크에 직접 노출하지 말 것
Linux
docker compose -f docker-compose.agent.yml run --rm agent python main.py healthWindows
docker compose -f docker-compose.windows.yml run --rm agent python main.py health문서를 data/docs/ 하위 디렉터리에 넣은 뒤 인덱스를 빌드합니다.
Linux
docker compose -f docker-compose.agent.yml run --rm agent python main.py build-index --rebuildWindows
docker compose -f docker-compose.windows.yml run --rm agent python main.py build-index --rebuild