BettaFish

KO | EN

gitlite — search

#javascript #ai #typescript #go #golang #android #machine-learning #rust #linux #docker #java #windows #vue #openai

(★ 42,006)

微舆:人人可用的多Agent舆情分析助手，打破信息茧房，还原舆情原貌，预测未来走向，辅助决策！从0实现，不依赖任何框架。

BettaFish 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

![BettaFish Logo](static/image/logo_compressed.png)
[![666ghj%2FBettaFish | Trendshift](https://trendshift.io/api/badge/repositories/15286)](https://trendshift.io/repositories/15286)
[![666ghj%2FBettaFish | Trendshift](./static/image/logo_aihubmix.png)](https://aihubmix.com/?aff=8Ds9) 
[![666ghj%2FBettaFish | Trendshift](./static/image/logo_anspire.png)](https://open.anspire.cn/?share_code=3E1FUOUH)
[![GitHub Stars](https://img.shields.io/github/stars/666ghj/BettaFish?style=flat-square)](https://github.com/666ghj/BettaFish/stargazers)
[![GitHub Watchers](https://img.shields.io/github/watchers/666ghj/BettaFish?style=flat-square)](https://github.com/666ghj/BettaFish/watchers)
[![GitHub Forks](https://img.shields.io/github/forks/666ghj/BettaFish?style=flat-square)](https://github.com/666ghj/BettaFish/network)
[![GitHub Issues](https://img.shields.io/github/issues/666ghj/BettaFish?style=flat-square)](https://github.com/666ghj/BettaFish/issues)
[![GitHub Pull Requests](https://img.shields.io/github/issues-pr/666ghj/BettaFish?style=flat-square)](https://github.com/666ghj/BettaFish/pulls)
[![GitHub License](https://img.shields.io/github/license/666ghj/BettaFish?style=flat-square)](https://github.com/666ghj/BettaFish/blob/main/LICENSE)
[![Version](https://img.shields.io/badge/version-v1.2.1-green.svg?style=flat-square)](https://github.com/666ghj/BettaFish)
[![Docker](https://img.shields.io/badge/Docker-Build-2496ED?style=flat-square&logo=docker&logoColor=white)](https://hub.docker.com/)
[English](./README-EN.md) | [中文文档](./README.md)

> [!IMPORTANT]
> 저희가 새롭게 출시한 예측 엔진을 확인해 보세요: [MiroFish-简洁通用的群体智能引擎，预测万物](https://github.com/666ghj/MiroFish)
>
> ![banner](static/image/MiroFish_logo_compressed.jpeg)
>
> "데이터 분석의 세 가지 도구" 전면 연결: MiroFish의 공식 출시를 기쁘게 알립니다! 마지막 조각이 채워짐으로써 BettaFish(데이터 수집 및 분석)부터 MiroFish(전체 예측)까지의 완전한 파이프라인이 구축되었습니다. 이로써 원시 데이터부터 지능형 의사결정까지의 폐루프가 완성되어 미래 예측이 가능해졌습니다!
## ⚡ 프로젝트 개요
"**미위(微舆)**"는 0부터 직접 구현한 혁신적인 멀티 에이전트(Multi-Agent) 여론 분석 시스템으로, 정보 격차를 해소하고 여론의 본모습을 복원하며 미래 추세를 예측하고 의사결정을 지원합니다. 사용자는 마치 채팅하듯 분석 요구사항을 제시하기만 하면, 에이전트가 국내외 30개 이상의 주요 소셜 미디어와 수백만 개의 대중 댓글을 전자동으로 분석하기 시작합니다.
> "미위"는 "미위(微鱼)"와 발음이 유사하며, BettaFish는 몸집은 매우 작지만 투지 넘치고 아름다운 물고기로 "작지만 강력하며, 도전을 두려워하지 않는" 상징성을 지닙니다.
"武汉大学舆情(우한대학교 여론)"을 예시로 시스템이 생성한 연구 보고서를 확인해 보세요: [武汉大学品牌声誉深度分析报告](./final\_reports/final\_report\_\_20250827\_131630.html)
"武汉大学舆情(우한대학교 여론)"을 예시로 한 전체 실행 과정을 담은 영상을 확인해 보세요: [视频-武汉大学品牌声誉深度分析报告](https://www.bilibili.com/video/BV1TH1WBxEWN/?vd\_source=da3512187e242ce17dceee4c537ec7a6#reply279744466833)
보고서의 품질뿐만 아니라, 동종 제품과 비교하여 당사만의 🚀6가지 우위 요소를 갖추고 있습니다:
1. **AI 기반의 전 영역 모니터링**: AI 크롤러 클러스터가 24시간 365일 중단 없이 작동하여 웨이보(微博), 샤오홍슈(小红书), 더이우/더우인(抖音), 콰이쇼우(快手) 등 국내외 10개 이상의 주요 소셜 미디어를 포괄적으로 커버합니다. 핫 토픽을 실시간으로 포착할 뿐만 아니라 대규모 사용자 댓글까지 파고들어 가장 진실하고 광범위한 대중의 목소리를 들을 수 있게 합니다.
2. **LLM을 뛰어넘는 복합 분석 엔진**: 설계된 5가지 전문 에이전트에만 의존하지 않고, 파인튜닝 모델, 통계 모델 등의 미들웨어를 융합했습니다. 다중 모델의 협업을 통해 분석 결과의 깊이, 정확성, 그리고 다차원적인 시각을 보장합니다.
3. ** 강력한 멀티모달 역량**: 텍스트와 이미지의 한계를 뛰어넘어 더우인, 콰이쇼우 등의 숏폼 비디오 콘텐츠를 깊이 있게 분석할 수 있으며, 현대 검색 엔진의 날씨, 캘린더, 주식 등의 구조화된 멀티모달 정보 카드를 정밀하게 추출하여 여론 동향을 완벽하게 파악할 수 있도록 합니다.
4. **에이전트 "포럼" 협업 메커니즘**: 서로 다른 에이전트에 고유한 툴셋과 사고방식을 부여하고 토론 사회자 모델을 도입하여 "포럼" 메커니즘을 통한 연쇄적 사고(Chain of Thought)의 충돌과 토론을 진행합니다. 이는 단일 모델의 사고 한계와 소통으로 인한 동질화를 방지할 뿐만 아니라, 더 높은 품질의 집단 지성과 의사결정 지원을 이끌어냅니다.
5. **공/사유 데이터의 심리스(Seamless) 융합**: 플랫폼은 공개된 여론뿐만 아니라 높은 보안성의 인터페이스를 제공하여, 내부 비즈니스 데이터베이스와 여론 데이터를 원활하게 통합할 수 있도록 지원합니다. 데이터 장벽을 허물고 버티컬 비즈니스에 "외부 트렌드 + 내부 인사이트"라는 강력한 분석 능력을 제공합니다.
6. **경량화 및 고확장성 프레임워크**: 순수 Python 모듈식 설계를 바탕으로 경량화 및 원클릭 배포를 실현합니다. 코드 구조가 명확하여 개발자가 커스텀 모델과 비즈니스 로직을 손쉽게 통합할 수 있으며, 플랫폼의 빠른 확장과 심층 커스터마이징이 가능합니다.
**여론에서 시작하되, 여론에만 머물지 않습니다**."미위"의 목표는 모든 비즈니스 시나리오를 구동하는 간결하고 범용적인 데이터 분석 엔진이 되는 것입니다.
> 예시를 들자면, 에이전트 툴셋의 API 파라미터와 프롬프트만 간단히 수정하면 금융 분야의 시장 분석 시스템으로 탈바꿈시킬 수 있습니다.
>
> 활발히 논의 중인 L커뮤니티 프로젝트 토론 게시글 첨부: https://linux.do/t/topic/1009280
>
> L커뮤니티 유저가 작성한 평가글 확인 [开源项目(微舆)与manus|minimax|ChatGPT|Perplexity对比](https://linux.do/t/topic/1148040)

![banner](static/image/system_schematic.png)
전통적인 데이터 대시보드와는 안녕입니다. "미위"에서는 모든 것이 간단한 질문 하나로 시작되며, 대화하듯 분석 요구사항을 제시하기만 하면 됩니다.

## 🪄 스폰서
LLM 모델 API 스폰서:[![666ghj%2FBettaFish | Trendshift](./static/image/logo_aihubmix.png)](https://aihubmix.com/?aff=8Ds9)

AI 웹 검색, 파일 파싱 및 웹페이지 콘텐츠 크롤링 등 에이전트 핵심 역량 제공업체:[![666ghj%2FBettaFish | Trendshift](./static/image/logo_anspire.png)](https://open.anspire.cn/?share_code=3E1FUOUH)
Anspire Open은 에이전트 시대를 선도하는 인프라 제공업체입니다. 강력한 에이전트를 구축하는 데 필요한 핵심 역량 스택을 개발자에게 제공하며, 현재 AI 웹 검색【다양한 버전, 매우 경쟁력 있는 가격】, 파일 파싱【기간 한정 무료】 및 웹페이지 콘텐츠 크롤링【기간 한정 무료】, 클라우드 브라우저 자동화(Anspire Browser Agent)【비공개 테스트】, 다중 턴 재작성 등의 서비스를 출시하여 에이전트가 복잡한 디지털 세계를 연결하고 조작할 수 있는 탄탄한 기반을 지속적으로 제공하고 있습니다. Dify, Coze, Yuanqi 등 주류 에이전트 플랫폼에 원활하게 통합될 수 있습니다. 투명한 포인트 과금 체계와 모듈식 설계를 통해 기업에 효율적이고 저렴한 맞춤형 지원을 제공하고 지능화 업그레이드 프로세스를 가속화합니다.
## 🏗️ 시스템 아키텍처
### 전체 아키텍처 다이어그램
**Insight Agent** 사유 데이터베이스 마이닝: 사유 여론 데이터베이스를 심층 분석하는 AI 에이전트
**Media Agent** 멀티모달 콘텐츠 분석: 강력한 멀티모달 능력을 갖춘 AI 에이전트
**Query Agent** 정밀 정보 검색: 국내외 웹 검색 능력을 갖춘 AI 에이전트
**Report Agent** 스마트 보고서 생성: 템플릿이 내장된 다중 턴 보고서 생성 AI 에이전트

![banner](static/image/framework.png)

### 완전한 분석 프로세스 1회
| 단계 | 단계 명칭 | 주요 작업 | 참여 컴포넌트 | 루프 특성 |
|------|----------|----------|----------|----------|
| 1 | 사용자 질문 | Flask 메인 앱에서 검색 쿼리 수신 | Flask 메인 앱 | - |
| 2 | 병렬 시작 | 3개의 에이전트가 동시에 작업 시작 | Query Agent, Media Agent, Insight Agent | - |
| 3 | 예비 분석 | 각 에이전트가 전용 툴을 사용하여 개요 검색 수행 | 각 에이전트 + 전용 툴셋 | - |
| 4 | 전략 수립 | 예비 결과를 바탕으로 청크별 연구 전략 수립 | 각 에이전트 내부 의사결정 모듈 | - |
| 5-N | **루프 단계** | **포럼 협업 + 심층 연구** | **ForumEngine + 모든 에이전트** | **다중 턴 루프** |
| 5.1 | 심층 연구 | 각 에이전트가 포럼 사회자의 안내에 따라 특화 검색 수행 | 각 에이전트 + 성찰 메커니즘 + 포럼 안내 | 매 루프마다 |
| 5.2 | 포럼 협업 | ForumEngine이 에이전트 발언 모니터링 및 사회자 안내 생성 | ForumEngine + LLM 사회자 | 매 루프마다 |
| 5.3 | 소통 융합 | 각 에이전트가 토론 내용에 따라 연구 방향 조정 | 각 에이전트 + forum\_reader 툴 | 매 루프마다 |
| N+1 | 결과 통합 | Report Agent가 모든 분석 결과와 포럼 내용 수집 | Report Agent | - |
| N+2 | IR 중간 표현 | 템플릿 및 스타일 동적 선택, 메타데이터 다중 턴 생성, IR 중간 표현으로 제본 | Report Agent + 템플릿 엔진 | - |
| N+3 | 보고서 생성 | 청크 단위 품질 검사, IR 기반으로 대화형 HTML 보고서 렌더링 | Report Agent + 제본 엔진 | - |
### 프로젝트 코드 구조 트리
```
BettaFish/
├── QueryEngine/ # 국내외 뉴스 광범위 검색 Agent
│ ├── agent.py # Agent 메인 로직, 검색 및 분석 프로세스 조율
│ ├── llms/ # LLM 인터페이스 캡슐화
│ ├── nodes/ # 처리 노드: 검색, 포맷팅, 요약 등
│ ├── tools/ # 국내외 뉴스 검색 툴셋
│ ├── utils/ # 유틸리티 함수
│ ├── state/ # 상태 관리
│ ├── prompts/ # 프롬프트 템플릿
│ └── ...
├── MediaEngine/ # 강력한 멀티모달 이해 Agent
│ ├── agent.py # Agent 메인 로직, 비디오/이미지 등 멀티모달 콘텐츠 처리
│ ├── llms/ # LLM 인터페이스 캡슐화
│ ├── nodes/ # 처리 노드: 검색, 포맷팅, 요약 등
│ ├── tools/ # 멀티모달 검색 툴셋
│ ├── utils/ # 유틸리티 함수
│ ├── state/ # 상태 관리
│ ├── prompts/ # 프롬프트 템플릿
│ └── ...
├── InsightEngine/ # 사유 데이터베이스 마이닝 Agent
│ ├── agent.py # Agent 메인 로직, 데이터베이스 쿼리 및 분석 조율
│ ├── llms/ # LLM 인터페이스 캡슐화
│ │ └── base.py # 통합된 OpenAI 호환 클라이언트
│ ├── nodes/ # 처리 노드: 검색, 포맷팅, 요약 등
│ │ ├── base\_node.py # 기본 노드 클래스
│ │ ├── search\_node.py # 검색 노드
│ │ ├── formatting\_node.py # 포맷팅 노드
│ │ ├── report\_structure\_node.py # 보고서 구조 노드
│ │ └── summary\_node.py # 요약 노드
│ ├── tools/ # 데이터베이스 쿼리 및 분석 툴셋
│ │ ├── keyword\_optimizer.py # Qwen 키워드 최적화 미들웨어
│ │ ├── search.py # 데이터베이스 조작 툴셋 (토픽 검색, 댓글 수집 등)
│ │ └── sentiment\_analyzer.py # 감성 분석 통합 툴
│ ├── utils/ # 유틸리티 함수
│ │ ├── config.py # 설정 관리
│ │ ├── db.py # SQLAlchemy 비동기 엔진 및 읽기 전용 쿼리 캡슐화
│ │ └── text\_processing.py # 텍스트 처리 툴
│ ├── state/ # 상태 관리
│ │ └── state.py # Agent 상태 정의
│ ├── prompts/ # 프롬프트 템플릿
│ │ └── prompts.py # 각종 프롬프트
│ └── \_\_init\_\_.py
├── ReportEngine/ # 다중 턴 보고서 생성 Agent
│ ├── agent.py # 총괄 스케줄러: 템플릿 선택→레이아웃→분량→챕터→렌더링
│ ├── flask\_interface.py # Flask/SSE 진입점, 작업 대기열 및 스트리밍 이벤트 관리
│ ├── llms/ # OpenAI 호환 LLM 캡슐화
│ │ └── base.py # 통합된 스트리밍/재시도 클라이언트
│ ├── core/ # 핵심 기능: 템플릿 파싱, 챕터 스토리지, 문서 제본
│ │ ├── template\_parser.py # Markdown 템플릿 슬라이싱 및 slug 생성
│ │ ├── chapter\_storage.py # 챕터 run 디렉토리, manifest 및 raw 스트림 쓰기
│ │ └── stitcher.py # Document IR 제본기, 앵커/메타데이터 보완
│ ├── ir/ # 보고서 중간 표현(IR) 계약 및 검증
│ │ ├── schema.py # 블록/마크업 Schema 상수로 정의
│ │ └── validator.py # 챕터 JSON 구조 검증기
│ ├── nodes/ # 전체 프로세스 추론 노드
│ │ ├── base\_node.py # 노드 베이스 클래스 + 로깅/상태 훅
│ │ ├── template\_selection\_node.py # 템플릿 후보 수집 및 LLM 필터링
│ │ ├── document\_layout\_node.py # 제목/목차/테마 디자인
│ │ ├── word\_budget\_node.py # 분량 기획 및 챕터 지시사항 생성
│ │ └── chapter\_generation\_node.py # 챕터급 JSON 생성 + 검증
│ ├── prompts/ # 프롬프트 라이브러리 및 Schema 설명
│ │ └── prompts.py # 템플릿 선택/레이아웃/분량/챕터 프롬프트
│ ├── renderers/ # IR 렌더러
│ │ ├── html\_renderer.py # Document IR → 대화형 HTML
│ │ ├── pdf\_renderer.py # HTML → PDF 내보내기 (WeasyPrint)
│ │ ├── pdf\_layout\_optimizer.py # PDF 레이아웃 최적화기
│ │ └── chart\_to\_svg.py # 차트 변환 SVG 툴
│ ├── state/ # 작업/메타데이터 상태 모델
│ │ └── state.py # ReportState 및 직렬화 툴
│ ├── utils/ # 설정 및 보조 툴
│ │ ├── config.py # Pydantic Settings 및 프린트 도우미
│ │ ├── dependency\_check.py # 의존성 검사 툴
│ │ ├── json\_parser.py # JSON 파싱 툴
│ │ ├── chart\_validator.py # 차트 검증 툴
│ │ └── chart\_repair\_api.py # 차트 복구 API
│ ├── report\_template/ # Markdown 템플릿 라이브러리
│ │ ├── 企业品牌声誉分析报告.md
│ │ └── ...
│ └── \_\_init\_\_.py
├── ForumEngine/ # 포럼 엔진: Agent 협업 메커니즘
│ ├── monitor.py # 로그 모니터링 및 포럼 관리 핵심
│ ├── llm\_host.py # 포럼 사회자 LLM 모듈
│ └── \_\_init\_\_.py
├── MindSpider/ # 소셜 미디어 크롤러 시스템
│ ├── main.py # 크롤러 메인 프로그램 진입점
│ ├── config.py # 크롤러 설정 파일
│ ├── BroadTopicExtraction/ # 토픽 추출 모듈
│ │ ├── main.py # 토픽 추출 메인 프로그램
│ │ ├── database\_manager.py # 데이터베이스 관리자
│ │ ├── get\_today\_news.py # 오늘의 뉴스 가져오기
│ │ └── topic\_extractor.py # 토픽 추출기
│ ├── DeepSentimentCrawling/ # 심층 여론 크롤링 모듈
│ │ ├── main.py # 심층 크롤링 메인 프로그램
│ │ ├── keyword\_manager.py # 키워드 관리자
│ │ ├── platform\_crawler.py # 플랫폼 크롤러 관리
│ │ └── MediaCrawler/ # 소셜 미디어 크롤러 핵심
│ │ ├── main.py
│ │ ├── config/ # 플랫폼별 설정
│ │ ├── media\_platform/ # 플랫폼별 크롤러 구현
│ │ └── ...
│ └── schema/ # 데이터베이스 구조 정의
│ ├── db\_manager.py # 데이터베이스 관리자
│ ├── init\_database.py # 데이터베이스 초기화 스크립트
│ ├── mindspider\_tables.sql # 데이터베이스 테이블 구조 SQL
│ ├── models\_bigdata.py # 대규모 미디어 여론 테이블의 SQLAlchemy 매핑
│ └── models\_sa.py # DailyTopic/Task 등 확장 테이블 ORM 모델
├── SentimentAnalysisModel/ # 감성 분석 모델 모음
│ ├── WeiboSentiment\_Finetuned/ # 파인튜닝된 BERT/GPT-2 모델
│ │ ├── BertChinese-Lora/ # BERT 중국어 LoRA 파인튜닝
│ │ │ ├── train.py
│ │ │ ├── predict.py
│ │ │ └── ...
│ │ └── GPT2-Lora/ # GPT-2 LoRA 파인튜닝
│ │ ├── train.py
│ │ ├── predict.py
│ │ └── ...
│ ├── WeiboMultilingualSentiment/ # 다국어 감성 분석
│ ├── train.py
│ ├── predict.py
│ └── ...
│ ├── WeiboSentiment\_SmallQwen/ # 소형 파라미터 Qwen3 파인튜닝
│ │ ├── train.py
│ │ ├── predict\_universal.py
│ │ └── ...
│ └── WeiboSentiment\_MachineLearning/ # 전통 머신러닝 방식
│ ├── train.py
│ ├── predict.py
│ └── ...
├── SingleEngineApp/ # 단일 Agent의 Streamlit 애플리케이션
│ ├── query\_engine\_streamlit\_app.py # QueryEngine 독립 실행형 앱
│ ├── media\_engine\_streamlit\_app.py # MediaEngine 독립 실행형 앱
│ └── insight\_engine\_streamlit\_app.py # InsightEngine 독립 실행형 앱
├── query\_engine\_streamlit\_reports/ # QueryEngine 단일 앱 실행 출력 결과
├── media\_engine\_streamlit\_reports/ # MediaEngine 단일 앱 실행 출력 결과
├── insight\_engine\_streamlit\_reports/ # InsightEngine 단일 앱 실행 출력 결과
├── templates/ # Flask 프론트엔드 템플릿
│ └── index.html # 메인 인터페이스 HTML
├── static/ # 정적 리소스
│ ├── image/ # 이미지 리소스
│ │ └── ...
│ ├── Partial README for PDF Exporting/ # PDF 내보내기 의존성 설정 설명
│ └── v2\_report\_example/ # 보고서 렌더링 예시
│ └── report\_all\_blocks\_demo/ # 전체 블록 유형 데모 (HTML/PDF/MD)
├── logs/ # 실행 로그 디렉토리
├── final\_reports/ # 최종 생성된 보고서 파일
│ ├── ir/ # 보고서 IR JSON 파일
│ └── \*.html # 최종 HTML 보고서
├── utils/ # 공통 유틸리티 함수
│ ├── forum\_reader.py # Agent 간 포럼 통신 툴
│ ├── github\_issues.py # GitHub Issue 링크 및 오류 안내 통합 생성
│ └── retry\_helper.py # 네트워크 요청 재시도 메커니즘 툴
├── tests/ # 단위 테스트 및 통합 테스트
│ ├── run\_tests.py # pytest 진입점 스크립트
│ ├── test\_monitor.py # ForumEngine 모니터링 단위 테스트
│ ├── test\_report\_engine\_sanitization.py # ReportEngine 보안성 테스트
│ └── ...
├── app.py # Flask 메인 앱 진입점
├── config.py # 전역 설정 파일
├── .env.example # 환경 변수 예시 파일
├── docker-compose.yml # Docker 멀티 서비스 오케스트레이션 설정
├── Dockerfile # Docker 이미지 빌드 파일
├── requirements.txt # Python 의존성 패키지 목록
├── regenerate\_latest\_html.py # 최신 챕터를 사용하여 재제본 및 HTML 렌더링
├── regenerate\_latest\_md.py # 최신 챕터를 사용하여 재제본 및 Markdown 렌더링
├── regenerate\_latest\_pdf.py # PDF 재생성 툴 스크립트
├── report\_engine\_only.py # Report Engine 커맨드 라인 버전
├── README.md # 중국어 설명 문서
├── README-EN.md # 영문 설명 문서
├── CONTRIBUTING.md # 중국어 기여 가이드
├── CONTRIBUTING-EN.md # 영문 기여 가이드
└── LICENSE # GPL-2.0 오픈소스 라이선스
```
## 🚀 빠른 시작 (Docker)
### 1. 프로젝트 실행
`.env.example` 파일을 복사하여 `.env` 라는 이름으로 지정한 후, 요구에 맞게 `.env` 파일 내의 환경 변수를 설정합니다.
백그라운드에서 모든 서비스를 시작하려면 다음 명령어를 실행하세요:
```bash
docker compose up -d
```
> **참고: 이미지 다운로드 속도가 느린 경우**, 기존 `docker-compose.yml` 파일 내에 **주석** 형태로 대체 가능한 백업 이미지 주소를 제공해 두었습니다.
### 2. 설정 설명
#### 데이터베이스 설정 (PostgreSQL)
다음 파라미터에 따라 데이터베이스 연결 정보를 설정해 주세요. MySQL도 지원하므로 필요에 따라 수정할 수 있습니다:
| 설정 항목 | 입력 값 | 설명 |
| :--- | :--- | :--- |
| `DB\_HOST` | `db` | 데이터베이스 서비스 이름 (`docker-compose.yml` 내 서비스 이름에 해당) |
| `DB\_PORT` | `5432` | 기본 PostgreSQL 포트 |
| `DB\_USER` | `bettafish` | 데이터베이스 사용자 이름 |
| `DB\_PASSWORD` | `bettafish` | 데이터베이스 비밀번호 |
| `DB\_NAME` | `bettafish` | 데이터베이스 이름 |
| **기타** | **기본값 유지** | 데이터베이스 커넥션 풀 등 기타 파라미터는 기본 설정을 유지해 주세요. |
#### 대규모 언어 모델(LLM) 설정
> 모든 LLM 호출은 OpenAI의 API 인터페이스 표준을 사용합니다.
데이터베이스 설정이 완료된 후, **모든 LLM 관련 파라미터**를 정상적으로 설정하여 시스템이 선택하신 LLM 서비스에 연결할 수 있도록 하세요.
위의 모든 설정을 완료하고 저장하면 시스템이 정상적으로 실행될 수 있습니다.
## 🔧 소스 코드 실행 가이드
> 만약 Agent 시스템 구축을 처음 배우는 중이라면, 매우 간단한 데모부터 시작해 보세요: [Deep Search Agent Demo](https://github.com/666ghj/DeepSearchAgent-Demo)
### 환경 요구사항
- **운영체제**: Windows, Linux, MacOS
- **Python 버전**: 3.9+
- **Conda**: Anaconda 또는 Miniconda
- **데이터베이스**: PostgreSQL (추천) 또는 MySQL
- **메모리**: 2GB 이상 권장
### 1. 환경 생성
#### Conda를 사용하는 경우
```bash
# conda 환경 생성
conda create -n your\_conda\_name python=3.11
conda activate your\_conda\_name
```
#### uv를 사용하는 경우
```bash
# uv 환경 생성
uv venv --python 3.11 # 3.11 환경 생성
```
### 2. PDF 내보내기에 필요한 시스템 의존성 설치 (선택사항)
이 부분에 대한 자세한 설정 설명이 있습니다: [配置所需依赖](./static/Partial%20README%20for%20PDF%20Exporting/README.md)
### 3. 의존성 패키지 설치
> 단계 2를 건너뛴 경우 weasyprint 라이브러리가 설치되지 않을 수 있으며, PDF 기능이 정상적으로 작동하지 않을 수 있습니다.
```bash
# 기본 의존성 설치
pip install -r requirements.txt
# uv 버전 명령어 (더 빠른 설치)
uv pip install -r requirements.txt
# 로컬 감성 분석 모델을 사용하고 싶지 않다면 (연산 요구량이 매우 적으며 기본적으로 cpu 버전이 설치됨), 해당 파일 내의 "머신러닝" 부분을 주석 처리한 후 명령어를 실행하세요.
```
### 4. Playwright 브라우저 드라이버 설치
```bash
# 브라우저 드라이버 설치 (크롤러 기능용)
playwright install chromium
```
### 5. LLM 및 데이터베이스 설정
프로젝트 루트 디렉토리의 `.env.example` 파일을 복사하여 `.env`로 이름을 바꿉니다.
`.env` 파일을 편집하여 API 키를 입력합니다(자신의 모델이나 검색 프록시를 선택할 수도 있으며, 자세한 내용은 루트 디렉토리의 `.env.example` 파일이나 루트 디렉토리의 config.py 내 설명을 참조하세요):
```bash
# ====================== 데이터베이스 설정 ======================
# 데이터베이스 호스트, 예: localhost 또는 127.0.0.1
DB\_HOST=your\_db\_host
# 데이터베이스 포트 번호, postgresql 기본값은 5432, mysql 기본값은 3306
DB\_PORT=5432
# 데이터베이스 사용자 이름
DB\_USER=your\_db\_user
# 데이터베이스 비밀번호
DB\_PASSWORD=your\_db\_password
# 데이터베이스 이름
DB\_NAME=your\_db\_name
# 데이터베이스 문자 세트, utf8mb4 권장 (이모지 호환)
DB\_CHARSET=utf8mb4
# 데이터베이스 유형 postgresql 또는 mysql
DB\_DIALECT=postgresql
# 데이터베이스는 초기화가 필요 없으며, app.py 실행 시 자동으로 감지됩니다.
# ====================== LLM 설정 ======================
# OpenAI 요청 형식과 호환되는 한, 각 파트의 LLM에 사용되는 API를 변경할 수 있습니다.
# 설정 파일 내부에는 각 Agent별 추천 LLM이 제공되어 있으며, 최초 배포 시 추천 설정을 먼저 참고해 주세요.
# Insight Agent
INSIGHT\_ENGINE\_API\_KEY=
INSIGHT\_ENGINE\_BASE\_URL=
INSIGHT\_ENGINE\_MODEL\_NAME=
# Media Agent
...
```
### 6. 시스템 시작
#### 6.1 전체 시스템 시작 (추천)
```bash
# 프로젝트 루트 디렉토리에서 conda 환경 활성화
conda activate your\_conda\_name
# 메인 애플리케이션 실행
python app.py
```
uv 버전 시작 명령어
```bash
# 프로젝트 루트 디렉토리에서 uv 환경 활성화
.venv\Scripts\activate
# 메인 애플리케이션 실행
python app.py
```
> 참고 1: 실행 종료 후 Streamlit 앱이 비정상적으로 종료되어 포트를 계속 점유할 수 있습니다. 이때 포트를 점유하고 있는 프로세스를 찾아 kill 하시면 됩니다.
> 참고 2: 데이터 크롤링은 별도로 조작해야 하며, 6.3 가이드를 참조하세요.
http://localhost:5000 에 접속하여 전체 시스템을 이용할 수 있습니다.
#### 6.2 특정 Agent 개별 시작
```bash
# QueryEngine 시작
streamlit run SingleEngineApp/query\_engine\_streamlit\_app.py --server.port 8503
# MediaEngine 시작
streamlit run SingleEngineApp/media\_engine\_streamlit\_app.py --server.port 8502
# InsightEngine 시작
streamlit run SingleEngineApp/insight\_engine\_streamlit\_app.py --server.port 8501
```
#### 6.3 크롤러 시스템 단독 사용
이 부분에 대한 자세한 설정 문서가 있습니다: [MindSpider 사용 설명](./MindSpider/README.md)

![banner](MindSpider/img/example.png)
MindSpider 실행 예시

```bash
# 크롤러 디렉토리로 이동
cd MindSpider
# 프로젝트 초기화
python main.py --setup
# 토픽 추출 실행 (핫 뉴스와 키워드 획득)
python main.py --broad-topic
# 전체 크롤러 프로세스 실행
python main.py --complete --date 2024-01-20
# 토픽 추출만 실행
python main.py --broad-topic --date 2024-01-20
# 심층 크롤링만 실행
python main.py --deep-sentiment --platforms xhs dy wb
```
#### 6.4 커맨드 라인 보고서 생성 툴
이 툴은 세 가지 분석 엔진의 실행 단계를 건너뛰고 최신 로그 파일을 직접 읽어들여, 웹 인터페이스 없이 종합 보고서를 생성합니다(파일 증분 검증 단계는 생략됨). 기본적으로 PDF 생성 후 자동으로 Markdown을 생성합니다(파라미터로 비활성화 가능). 주로 보고서 생성 결과가 만족스럽지 않아 빠른 재시도가 필요한 경우나 Report Engine 디버깅 시 활성화됩니다.
```bash
# 기본 사용법 (파일명에서 자동으로 주제 추출)
python report\_engine\_only.py
# 보고서 주제 지정
python report\_engine\_only.py --query "토목공학 산업 분석"
# PDF 생성 건너뛰기 (시스템이 지원하더라도)
python report\_engine\_only.py --skip-pdf
# Markdown 생성 건너뛰기
python report\_engine\_only.py --skip-markdown
# 상세 로그 표시
python report\_engine\_only.py --verbose
# 도움말 정보 보기
python report\_engine\_only.py --help
```
**기능 설명:**
1. **의존성 자동 검사**: 프로그램이 PDF 생성에 필요한 시스템 의존성을 자동으로 검사하며, 누락된 경우 설치 안내를 제공합니다.
2. **최신 파일 가져오기**: 세 가지 엔진 디렉토리(`insight\_engine\_streamlit\_reports`, `media\_engine\_streamlit\_reports`, `query\_engine\_streamlit\_reports`)에서 최신 분석 보고서를 자동으로 가져옵니다.
3. **파일 확인**: 선택된 모든 파일 이름, 경로, 수정 시간을 표시하고 사용자 확인을 기다립니다 (기본값은 `y` 입력 시 계속, `n` 입력 시 종료).
4. **보고서 직접 생성**: 파일 증분 검사 절차를 건너뛰고 Report Engine을 직접 호출하여 종합 보고서를 생성합니다.
5. **파일 자동 저장**:
- HTML 보고서는 `final\_reports/` 디렉토리에 저장됩니다.
- PDF 보고서(의존성이 있는 경우)는 `final\_reports/pdf/` 디렉토리에 저장됩니다.
- Markdown 보고서(`--skip-markdown`으로 비활성화 가능)는 `final\_reports/md/` 디렉토리에 저장됩니다.
- 파일 네이밍 형식: `final\_report\_{주제}\_{타임스탬프}.html/pdf/md`
**주의사항:**
- 세 가지 엔진 디렉토리 중 최소한 하나에 `.md` 보고서 파일이 포함되어 있는지 확인하세요.
- 커맨드 라인 툴과 웹 인터페이스는 서로 독립적이며 서로 영향을 주지 않습니다.
- PDF 생성에는 시스템 의존성 설치가 필요합니다. 자세한 내용은 위 "PDF 내보내기에 필요한 시스템 의존성 설치" 부분을 참고하세요.
**최신 결과 빠른 재렌더링:**
- `regenerate\_latest\_html.py` / `regenerate\_latest\_md.py`: `CHAPTER\_OUTPUT\_DIR` 내 가장 최근 실행된 챕터 JSON으로부터 Document IR을 재제본하고 HTML 또는 Markdown을 직접 렌더링합니다.
- `regenerate\_latest\_pdf.py`: `final\_reports/ir` 안의 가장 최신 IR을 읽어들여 SVG 벡터 차트를 사용하여 PDF를 재내보내기 합니다.
## ⚙️ 고급 설정 (구형 방식, 현재는 프로젝트 루트 디렉토리의 .env 파일 관리로 통합되었으며, 다른 서브 에이전트들은 루트 디렉토리 설정을 자동으로 상속받습니다)
### 주요 파라미터 수정
#### Agent 설정 파라미터
각 Agent마다 전용 설정 파일이 있으며 필요에 따라 조정할 수 있습니다. 일부 예시는 다음과 같습니다:
```python
# QueryEngine/utils/config.py
class Config:
max\_reflections = 2 # 성찰 턴 수
max\_search\_results = 15 # 최대 검색 결과 수
max\_content\_length = 8000 # 최대 콘텐츠 길이
# MediaEngine/utils/config.py
class Config:
comprehensive\_search\_limit = 10 # 종합 검색 제한
web\_search\_limit = 15 # 웹 검색 제한
# InsightEngine/utils/config.py
class Config:
default\_search\_topic\_globally\_limit = 200 # 전역 검색 제한
default\_get\_comments\_limit = 500 # 댓글 수집 제한
max\_search\_results\_for\_llm = 50 # LLM에 전달할 최대 결과 수
```
#### 감성 분석 모델 설정
```python
# InsightEngine/tools/sentiment\_analyzer.py
SENTIMENT\_CONFIG = {
'model\_type': 'multilingual', # 선택 가능: 'bert', 'multilingual', 'qwen' 등
'confidence\_threshold': 0.8, # 신뢰도 임계값
'batch\_size': 32, # 배치 크기
'max\_sequence\_length': 512, # 최대 시퀀스 길이
}
```
### 다양한 LLM 모델 연동
OpenAI 호출 형식을 지원하는 모든 LLM 제공업체를 지원하며, `/config.py`에 해당하는 KEY, BASE\_URL, MODEL\_NAME을 기입하기만 하면 됩니다.
> OpenAI 호출 형식란 무엇인가요? 간단한 예시를 아래에 제공합니다:
>```python
>from openai import OpenAI
>
>client = OpenAI(api\_key="your\_api\_key",
> base\_url="https://aihubmix.com/v1")
>
>response = client.chat.completions.create(
> model="gpt-4o-mini",
> messages=[
> {'role': 'user',
> 'content': "추론 모델이 시장에 가져올 새로운 기회는 무엇인가요"}
> ],
>)
>
>complete\_response = response.choices[0].message.content
>print(complete\_response)
>```
### 감성 분석 모델 변경
시스템에는 다양한 감성 분석 방법이 통합되어 있으며 필요에 따라 선택할 수 있습니다:
#### 1. 다국어 감성 분석
```bash
cd SentimentAnalysisModel/WeiboMultilingualSentiment
python predict.py --text "This product is amazing!" --lang "en"
```
#### 2. 소형 파라미터 Qwen3 파인튜닝
```bash
cd SentimentAnalysisModel/WeiboSentiment\_SmallQwen
python predict\_universal.py --text "这次活动办得很成功"
```
#### 3. BERT 기반 파인튜닝 모델
```bash
# BERT 중국어 모델 사용
cd SentimentAnalysisModel/WeiboSentiment\_Finetuned/BertChinese-Lora
python predict.py --text "这个产品真的很不错"
```
#### 4. GPT-2 LoRA 파인튜닝 모델
```bash
cd SentimentAnalysisModel/WeiboSentiment\_Finetuned/GPT2-Lora
python predict.py --text "今天心情不太好"
```
#### 5. 전통 머신러닝 방식
```bash
cd SentimentAnalysisModel/WeiboSentiment\_MachineLearning
python predict.py --model\_type "svm" --text "服务态度需要改进"
```
### 커스텀 비즈니스 데이터베이스 연동
#### 1. 데이터베이스 연결 설정 수정
```python
# config.py 에 비즈니스 데이터베이스 설정 추가
BUSINESS\_DB\_HOST = "your\_business\_db\_host"
BUSINESS\_DB\_PORT = 3306
BUSINESS\_DB\_USER = "your\_business\_user"
BUSINESS\_DB\_PASSWORD = "your\_business\_password"
BUSINESS\_DB\_NAME = "your\_business\_database"
```
#### 2. 커스텀 데이터 접근 툴 생성
```python
# InsightEngine/tools/custom\_db\_tool.py
class CustomBusinessDBTool:
"""커스텀 비즈니스 데이터베이스 쿼리 툴"""
def \_\_init\_\_(self):
self.connection\_config = {
'host': config.BUSINESS\_DB\_HOST,
'port': config.BUSINESS\_DB\_PORT,
'user': config.BUSINESS\_DB\_USER,
'password': config.BUSINESS\_DB\_PASSWORD,
'database': config.BUSINESS\_DB\_NAME,
}
def search\_business\_data(self, query: str, table: str):
"""비즈니스 데이터 쿼리"""
# 비즈니스 로직 구현
pass
def get\_customer\_feedback(self, product\_id: str):
"""고객 피드백 데이터 획득"""
# 고객 피드백 쿼리 로직 구현
pass
```
#### 3. InsightEngine에 통합
```python
# InsightEngine/agent.py 에 커스텀 툴 통합
from .tools.custom\_db\_tool import CustomBusinessDBTool
class DeepSearchAgent:
def \_\_init\_\_(self, config=None):
# ... 기타 초기화 코드
self.custom\_db\_tool = CustomBusinessDBTool()
def execute\_custom\_search(self, query: str):
"""커스텀 비즈니스 데이터 검색 실행"""
return self.custom\_db\_tool.search\_business\_data(query, "your\_table")
```
### 커스텀 보고서 템플릿
#### 1. 웹 인터페이스에서 업로드
시스템은 커스텀 템플릿 파일(.md 또는 .txt 형식) 업로드를 지원하며, 보고서 생성 시 선택하여 사용할 수 있습니다.
#### 2. 템플릿 파일 생성
`ReportEngine/report\_template/` 디렉토리에 새로운 템플릿을 생성하면 에이전트가 가장 적합한 템플릿을 스스로 선택합니다.
## 🤝 기여 가이드
모든 형태의 기여를 환영합니다!
**다음 기여 가이드를 읽어주세요:**
- [CONTRIBUTING.md](./CONTRIBUTING.md)
## 🦖 다음 개발 계획
이제 시스템이 마지막 예측 단계를 완료했습니다! 접속하여 확인해 보세요 [MiroFish-预测万物]: https://github.com/666ghj/MiroFish

![banner](static/image/MiroFish_logo_compressed.jpeg)
![banner](static/image/banner_compressed.png)

## ⚠️ 면책 조항
**중요 알림: 본 프로젝트는 학습, 학술 연구 및 교육 목적으로만 사용됩니다.**
1. **준법성 성명**:
- 본 프로젝트의 모든 코드, 툴 및 기능은 학습, 학술 연구 및 교육 목적으로만 사용됩니다.
- 본 프로젝트를 어떠한 상업적 용도나 영리 목적으로 사용하는 것을 엄금합니다.
- 본 프로젝트를 위법, 규정 위반 또는 타인의 권익을 침해하는 행위에 사용하는 것을 엄금합니다.
2. **크롤러 기능 면책**:
- 프로젝트 내의 크롤러 기능은 기술 학습 및 연구 목적으로만 사용됩니다.
- 사용자는 대상 웹사이트의 robots.txt 프로토콜과 이용 약관을 반드시 준수해야 합니다.
- 사용자는 관련 법률 및 규정을 준수해야 하며 악의적인 크롤링이나 데이터 남용을 해서는 안 됩니다.
- 크롤러 기능 사용으로 인해 발생하는 모든 법적 결과는 사용자 본인이 부담합니다.
3. **데이터 사용 면책**:
- 프로젝트와 관련된 데이터 분석 기능은 학술 연구용으로만 제공됩니다.
- 분석 결과를 상업적 의사결정이나 영리 목적으로 사용하는 것을 엄금합니다.
- 사용자는 분석된 데이터의 합법성과 규정 준수 여부를 보장해야 합니다.
4. **기술 면책**:
- 본 프로젝트는 "있는 그대로" 제공되며 명시적이거나 암시적인 어떠한 보증도 제공하지 않습니다.
- 저자는 본 프로젝트를 사용하여 발생하는 어떠한 직간접적 손해에 대해서도 책임을 지지 않습니다.
- 사용자는 본 프로젝트의 적합성과 리스크를 스스로 평가해야 합니다.
5. **책임 제한**:
- 사용자는 본 프로젝트를 사용하기 전에 관련 법률 및 규정을 충분히 이해해야 합니다.
- 사용자는 자신의 사용 행위가 현지 법률 및 규정 요구사항을 충족하는지 확인해야 합니다.
- 법률 및 규정을 위반하여 본 프로젝트를 사용하여 발생하는 모든 결과는 사용자 본인이 부담합니다.
**본 프로젝트를 사용하기 전에 상기 면책 조항을 주의 깊게 읽고 이해해 주시기 바랍니다. 본 프로젝트를 사용하는 것은 상기 모든 조항에 동의하고 수락했음을 나타냅니다.**
## 📄 라이선스
본 프로젝트는 [GPL-2.0 라이선스](LICENSE)를 따릅니다. 자세한 내용은 LICENSE 파일을 참고하세요.
## 🎉 지원 및 연락처
### 도움 받기
자주 묻는 질문(FAQ): https://github.com/666ghj/BettaFish/issues/700
- **프로젝트 홈페이지**: [GitHub 저장소](https://github.com/666ghj/BettaFish)
- **버그 및 문제 피드백**: [Issues 페이지](https://github.com/666ghj/BettaFish/issues)
- **기능 제안**: [Discussions 페이지](https://github.com/666ghj/BettaFish/discussions)
### 연락처
- 📧 **이메일**: baifu.guohj@gmail.com
### 비즈니스 제휴
- **기업 맞춤형 개발**
- **빅데이터 서비스**
- **학술 제휴**
- **기술 교육**
## 👥 기여자
다음의 훌륭한 기여자분들께 감사드립니다:
[![Contributors](https://contrib.rocks/image?repo=666ghj/BettaFish)](https://github.com/666ghj/BettaFish/graphs/contributors)
## 🌟 공식 소통 채널 참여

![欢迎加入我们的技术交流QQ群！](https://capsule-render.vercel.app/api?type=waving&color=gradient&height=200§ion=header&text=欢迎加入我们的技术交流QQ群！&fontSize=40&fontAlignY=35&desc=扫描下方二维码加入群聊&descAlignY=55)
![BettaFish 기술 소통 그룹 QR 코드](static/image/QQ_Light_Horizenal.png)

## 📈 프로젝트 통계
[![BettaFish Star History Chart](static/image/star-history-light.svg)](https://github.com/666ghj/BettaFish)
![Alt](https://repobeats.axiom.co/api/embed/e04e3eea4674edc39c148a7845c8d09c1b7b1922.svg "Repobeats analytics image")

BettaFish

BettaFish 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

BettaFish

BettaFish 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README