<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/wandb/wandb/main/assets/logo-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/wandb/wandb/main/assets/logo-light.svg">
<img src="https://raw.githubusercontent.com/wandb/wandb/main/assets/logo-light.svg" width="600" alt="Weights & Biases">
</picture>
</p>
WandBot
WandBot은 Weights & Biases의 실험 추적(Experiment Tracking) 및 Weave를 위해 설계된 지원 도우미입니다.
What's New
<details>
<summary>wandbot v1.3.0</summary>
- 최신 wandb 문서 및 코드 + weave 문서 및 코드, 예제 colab, 교육 콘텐츠 사용 - chroma_index:v50 이용
- 쿼리 확장을 위해 Gemini flash-2.0 사용 (이전 gpt-4o)
- 응답 작성을 위해 GPT-4o 사용 (이전 gpt-4o)
- Cohere rerank-v3.5 사용 (이전 rerank-v2.0)
- 호스팅된 Chroma 사용 (이전 로컬 호스팅 Chroma)
- 현재 웹 검색 기능 비활성화
- 모든 설정을 configs 폴더로 이동
- 대부분의 langchain 의존성 제거
- LLM 및 EmbeddingModel 클래스 구현
- 더 강력한 평가 파이프라인, 재시도(retries), 오류 처리 및 cli 인자 추가
- 패키지 관리를 uv 사용으로 변경
- python 3.12로 업데이트
- 개발 중 환경 변수 로드를 위해 dotenv 추가
- 새 엔드포인트 추가, 현재는 검색기(retriever) 엔드포인트 제거
- 모든 API에 대한 오류 처리 및 재시도 개선
</details>
<details>
<summary>wandbot v1.2.0</summary>
이 릴리스에서는 여러 흥미로운 업데이트와 개선 사항을 소개합니다:
- 병렬 LLM 호출(Parallel LLM Calls): llama-index를 LECL로 교체하여 효율성을 높인 병렬 LLM 호출을 가능하게 했습니다.
- ChromaDB 통합(ChromaDB Integration): 메타데이터 필터링 및 속도를 활용하기 위해 FAISS에서 ChromaDB로 전환했습니다.
- 쿼리 인핸서 최적화(Query Enhancer Optimization): 쿼리 인핸서를 단일 LLM 호출로 작동하도록 개선했습니다.
- 모듈형 RAG 파이프라인(Modular RAG Pipeline): 명확성과 유지보수성을 향상시키기 위해 RAG 파이프라인을 세 가지 개별 모듈(질의 강화, 검색, 응답 합성)로 분할했습니다.
- 부모 문서 검색(Parent Document Retrieval): 문맥성(contextuality)을 높이기 위해 검색 모듈 내에 부모 문서 검색 기능을 도입했습니다.
- 하위 질의 답변(Sub-query Answering): 복잡한 질의를 보다 효과적으로 처리하기 위해 응답 합성 모듈에 하위 질의 답변 기능을 추가했습니다.
- API 재구성(API Restructuring): API를 검색, 데이터베이스 및 채팅 작업용 별도의 라우터로 재설계했습니다.
이러한 업데이트는 성능과 사용성 개선에 대한 지속적인 노력의 일환입니다.
평가 (Evaluation)
English
Knowledge base 업데이트]
(https://wandb.ai/wandbot/wandbot-eval/weave/evaluations?view=evaluations_2025-05-20_09-37-33-681&pin=%7B%22left%22%3A%5B%22summary.weave.trace_name%22%2C%22feedback%22%2C%22output.WandbotCorrectnessScorer.answer_correct.true_fraction%22%2C%22output.model_output.api_call_statuses.chat_error_info.has_error.true_count%22%2C%22output.model_output.api_call_statuses.chat_success.true_count%22%2C%22summary.weave.status%22%5D%2C%22right%22%3A%5B%5D%7D&peekPath=%2Fwandbot%2Fwandbot-eval%2Fcalls%2F0196ea1b-f8cb-7cf2-a22d-a8254ef6f67f%3FhideTraceTree%3D1) | 90.4 % | 5 | v54
| 1.3.3 | v1.3.3 prod, v61 index, 500 tok Flash thinking, Flash Lite stable, gpt-4o judge. Knowledge base update | 82 % | 5 | v61
참고 (Note)
- v1.3.1은 다음을 사용합니다:
- 응답 합성기(response synthesizer)로 claude Sonnet-3.7을 사용하며, 이는 gpt-4o-2024-11-20에서 업데이트된 것입니다.
- 한국어 및 일본어 버전의 문서를 제외하고, Fully Connected의 블로그 게시물도 제외한 업데이트된 인덱스를 사용합니다.
gpt-4-preview judge를 사용한 1.3.0rc와 gpt-4o judge를 사용한 1.3.0rc는 서로 다른 평가자(judge)로 평가된 동일한 Wandbot 시스템입니다.1.3.0rc (gpt-4o judge)와 1.3.0 prod 사이의 약 2.5% 개선은 주로 reranker-v3.5(2.0 버전에서 가져옴)와 flash-2.0-001(gpt-4o에서 가져옴)을 사용했기 때문입니다. 하지만 v1.3.0 prod 평가 이전의 평가에서는 총 490건 호출 중 10~12개의 오류가 있었으므로, 결과에 노이즈(noise)가 있을 수 있습니다.
Japanese
| wandbot version | Comment | response accuracy |
|---|
| 1.2.0 | our new enhanced wandbot | 56.3 % |
| 1.2.1 | add translation process | 71.9 % |
기능 (Features)
- WandBot은 다음을 사용합니다:
- 호스팅된 ChromaDB 벡터 스토어
- OpenAI의 v3 임베딩(embeddings)
- 쿼리 향상을 위한 Gemini flash-2.0
- 응답 합성(response synthesis)을 위한 GPT-4o
- Cohere의 재순위 지정 모델(re-ranking model)
- 주기적인 데이터 수집 및 리포트 생성을 통해 봇의 지속적인 개선에 기여합니다. 최신 데이터 수집 보고서는 여기에서 확인할 수 있습니다.
- 이 봇은 Discord와 Slack과 통합되어, 이러한 인기 협업 플랫폼과의 원활한 연동을 지원합니다.
- Weights & Biases Weave를 통한 로깅 및 분석으로 성능 모니터링과 지속적인 개선이 가능합니다.
- 모델 선택에 대한 폴백(fallback) 메커니즘을 갖추고 있습니다.
설치 (Installation)
본 프로젝트는 Python 버전 3.12로 구축되었으며, 의존성 관리를 위해 uv를 활용합니다. 필요한 의존성을 설치하려면 아래 단계를 따르십시오:
uv venv
uv sync
source .venv/bin/activate
...
사용법 (Usage)
WandBot 실행하기 (Running WandBot)
wandbot을 실행하기 전에 다음 환경 변수가 설정되어 있는지 확인하십시오:
OPENAI_API_KEY
COHERE_API_KEY
WANDB_API_KEY
...
만약 slack 또는 discord 앱을 실행하는 경우, 다음 키/토큰도 환경 변수로 설정해야 합니다:
SLACK_EN_APP_TOKEN
SLACK_EN_BOT_TOKEN
SLACK_EN_SIGNING_SECRET
...
그런 다음 앱을 설치하여 가상 환경에 모든 의존성을 설치합니다:
로컬 개발 (Local Development)
다음 명령어를 사용하여 wandbot을 로컬에서 시작하십시오:
uv run uvicorn wandbot.api.app:app --host 0.0.0.0 --port 8000
...
앱은 시작될 때 자동으로 초기화됩니다.
Modal 배포 (Modal Deployment)
Wandbot은 자동 확장(auto-scaling) 및 낮은 지연 시간(low latency)을 갖춘 서버리스 호스팅 환경인 Modal에 배포할 수 있습니다. 배포는 두 개의 별도 Modal 앱으로 나뉩니다:
- wandbot-api: FastAPI 서버
- wandbot-bots: Discord 및 Slack 봇
Modal API URL은 modal_config.py에 설정되어 있으며, .env 파일에서 WANDBOT_MODAL_API_URL을 설정하여 이를 덮어쓸 수도 있습니다.
deploy_all.sh 스크립트는 다음 작업을 수행합니다:
- API 서버 배포
- 봇 애플리케이션 배포
- 즉시 봇 시작 (24시간 동안 실행됨)
- 봇이 계속 실행되도록 시간별 크론 작업(cron job) 설정
자세한 Modal 배포 지침은 MODAL_DEPLOYMENT.md를 참조하십시오.
봇 설치 및 실행에 대한 더 자세한 지침은 리포지토리 루트에 있는 run.sh 파일을 참조하십시오.
이 명령어들을 실행하면 API, Slackbot, 그리고 Discord 봇 애플리케이션이 시작되어 Wandbot과 상호 작용하고 Weights & Biases 문서와 관련된 질문을 할 수 있게 됩니다.
평가 파이프라인 실행
평가 설정(Eval Config)
평가 설정은 여기에서 찾을 수 있으며, 트라이얼 횟수, Weave 병렬성(weave parallelism), Weave 로깅 세부 정보 및 디버그 모드를 설정하는 CLI 인수를 포함합니다: wandbot/src/wandbot/evaluation/eval_config.py
다음 평가 세트가 사용됩니다:
English evaluation dataset
- ref:
weave:///wandbot/wandbot-eval/object/wandbot_eval_data:eCQQ0GjM077wi4ykTWYhLPRpuGIaXbMwUGEB7IyHlFU
Japanese evaluation dataset
- ref:
weave:///wandbot/wandbot-eval-jp/object/wandbot_eval_data_jp:oCWifIAtEVCkSjushP0bOEc5GnhsMUYXURwQznBeKLA
종속성(Dependencies)
프로덕션 종속성을 설치하여 wandbot이 설치되었는지 확인하고, 생성된 가상 환경(virtual env)을 활성화한 다음 평가 종속성을 설치하세요.
uv venv
uv sync
source .venv/bin/activate
...
환경 변수(Environment variables)
환경 변수(예: LLM 제공업체 키 등)를 .env 파일에서 설정했는지 확인하세요.
wandbot 앱 실행하기(Launch the wandbot app)
평가 요청을 병렬로 처리할 수 있도록 uvicorn 또는 gunicorn을 사용하여 N개의 워커(workers)를 실행할 수 있습니다. 참고로, Weave 평가(Weave Evaluations) 역시 병렬 호출 수에 제한이 있으며, 이는 WEAVE_PARALLELISM 환경 변수를 통해 설정됩니다. 이 값은 eval.py 파일에서 n_weave_parallelism 플래그를 사용하여 더 아래쪽에 설정되어 있습니다. 더 빠른 평가를 위해 wandbot을 8개의 워커로 실행하세요.
uvicorn
uv run uvicorn wandbot.api.app:app \
--host 0.0.0.0 \
--port 8000 \
...
테스트: 앱이 올바르게 실행되는지 확인하려면 chat/query 엔드포인트로 요청을 보내볼 수 있습니다. 30~90초 후에 wandbot으로부터 응답 페이로드(response payload)를 받게 될 것입니다:
curl -X POST \
http://localhost:8000/chat/query \
-H 'Content-Type: application/json' \
...
디버깅(Debugging)
평가 중 디버깅 목적으로는 위의 uvicorn 명령을 --workers 1을 사용하도록 변경하여 앱의 단일 인스턴스를 실행할 수 있습니다.
평가 실행하기(Run the evaluation)
W&B Weave 평가를 루트 wandbot 디렉토리에서 실행합니다. 가상 환경(virtual environment)이 활성화되어 있는지 확인하십시오. 기본적으로 wandbot의 확률적 특성(stochasticity)과 저희 LLM 평가자(LLM judge) 모두를 고려하여 샘플당 3회 평가가 수행됩니다.
- 디버깅을 위해
--debug 플래그를 전달하면 소수의 샘플에 대해서만 평가가 이루어집니다.
- weave가 병렬 평가 호출을 조정하려면
eval.py를 호출할 때 --n_weave_parallelism 플래그를 사용합니다.
- 모든 평가 옵션은
eval_config.py에서 확인하십시오.
source wandbot_venv/bin/activate
uv run src/wandbot/evaluation/eval.py
운영 환경(prod) 이전에 평가를 실행할 때는 항상 평가 샘플당 5회의 트라이얼을 실행합니다. 또한, API 속도 제한 문제(api rate limiting issues)로 인해 평가 결과가 왜곡될 수 있으므로 weave 병렬 처리 수준을 낮추는 것도 좋은 방법입니다:
caffeinate uv run src/wandbot/evaluation/eval.py --experiment_name <insert eval name> --n_trials 5 --n_weave_parallelism 4
디버깅 시, 단일 샘플에 대해 1회 트라이얼만 실행하는 경우:
uv run src/wandbot/evaluation/eval.py --debug --n_debug_samples=1 --n_trials=1
일본어 데이터셋에서 평가하기:
uv run src/wandbot/evaluation/eval.py --lang ja
각 샘플을 단 한 번만 평가하려면:
uv run src/wandbot/evaluation/eval.py --n_trials 1
데이터 수집 (Data Ingestion)
데이터 수집 모듈은 Weights & Biases 저장소에서 코드와 마크다운을 가져와 검색 증강 생성(retrieval augmented generation) 파이프라인용 벡터 저장소(vectorstores)에 주입합니다.
스크립트를 실행하기 전에 임베딩 모델 제공업체 및 원격 벡터 저장소 제공업체의 API 키가 설정되어 있는지 확인하십시오. 더 많은 팁은 아래 디버깅 단계를 참조하십시오.
저장소를 클론하려면 ~/.ssh/id_rsa에 .ssh 키가 있거나, 아직 없다면 생성해야 합니다:
ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa
그런 다음 수집 파이프라인 스크립트를 실행합니다:
uv run src/wandbot/ingestion/__main__.py
참고:
src/wandbot/configs/vector_store_config.py와 src/wandbot/configs/ingestion_config에 있는 구성 파일(configs)에 특별히 주의를 기울여야 합니다. 이 파일들에는 임베딩 모델, 임베딩 차원, 그리고 호스팅된 대(vs) 로컬 벡터 DB와 같은 중요한 설정들이 정의되어 있기 때문입니다. 또한, .env 파일에 VECTOR_STORE_API_KEY 환경 변수(env var)가 설정되어 있는지 확인하십시오.
데이터는 data/cache 디렉토리에 주입(ingested)되며, 이 과정에서 인제스션 프로세스의 각 단계별 개별 파일을 포함하여 세 개의 다른 디렉토리(raw_data, vectorstore)에 저장되는 것을 확인할 수 있습니다.