Skip to content

Commit a0e26eb

Browse files
author
Vitalij Bojatschkin
committed
Initial commit: RAG Dokumenten-Chatbot – FastAPI + React + AWS Bedrock + Qdrant
Anonymisiertes Praxisbeispiel basierend auf realen Projektmustern. Mehr unter https://bojatschkin.de
0 parents  commit a0e26eb

38 files changed

Lines changed: 2626 additions & 0 deletions

‎.env.example‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# AWS Bedrock Credentials
2+
# IAM User benötigt: AmazonBedrockFullAccess
3+
# Model Access in AWS Console aktivieren:
4+
# - Claude 3.5 Sonnet v2
5+
# - Titan Embeddings V2
6+
7+
AWS_ACCESS_KEY_ID=AKIAXXXXXXXXXXXXXXXX
8+
AWS_SECRET_ACCESS_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
9+
AWS_REGION=eu-central-1
10+
11+
# Qdrant Configuration (Optional - defaults aus docker-compose)
12+
# QDRANT_HOST=qdrant
13+
# QDRANT_PORT=6333
14+
# QDRANT_COLLECTION=documents
15+
16+
# Chunking Configuration
17+
# CHUNK_SIZE=512
18+
# CHUNK_OVERLAP=50
19+
20+
# Model IDs (Optional - defaults sind gesetzt)
21+
# BEDROCK_MODEL_ID=anthropic.claude-3-5-sonnet-20241022-v2:0
22+
# EMBEDDING_MODEL_ID=amazon.titan-embed-text-v2:0
23+
24+
# LLM Parameters (Optional)
25+
# LLM_MAX_TOKENS=2048
26+
# LLM_TEMPERATURE=0.3
27+
28+
# Retrieval (Optional)
29+
# RETRIEVAL_TOP_K=5
30+
31+
# Upload Limit (Optional)
32+
# MAX_UPLOAD_SIZE_MB=50
33+
34+
# CORS Origins (Optional - kommasepariert)
35+
# CORS_ORIGINS=http://localhost:3000,http://localhost:5173

‎.github/workflows/ci.yml‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
name: demo-ci
2+
3+
on:
4+
push:
5+
pull_request:
6+
7+
jobs:
8+
validate:
9+
runs-on: ubuntu-latest
10+
steps:
11+
- uses: actions/checkout@v4
12+
- name: Validate docker compose
13+
run: docker compose config
14+
- name: Verify README files
15+
run: |
16+
test -f README.md
17+
test -f README_EN.md
18+
- name: Set up Python
19+
uses: actions/setup-python@v5
20+
with:
21+
python-version: "3.12"
22+
- name: Lint backend
23+
run: |
24+
pip install ruff
25+
ruff check backend/app/
26+
- name: Verify .env.example
27+
run: test -f .env.example

‎.gitignore‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Python
2+
__pycache__/
3+
*.py[cod]
4+
*$py.class
5+
*.so
6+
.Python
7+
build/
8+
develop-eggs/
9+
dist/
10+
downloads/
11+
eggs/
12+
.eggs/
13+
lib/
14+
lib64/
15+
parts/
16+
sdist/
17+
var/
18+
wheels/
19+
pip-wheel-metadata/
20+
share/python-wheels/
21+
*.egg-info/
22+
.installed.cfg
23+
*.egg
24+
MANIFEST
25+
venv/
26+
ENV/
27+
env/
28+
.venv
29+
pip-log.txt
30+
pip-delete-this-directory.txt
31+
32+
# IDE
33+
.vscode/
34+
.idea/
35+
*.swp
36+
*.swo
37+
*~
38+
.DS_Store
39+
40+
# Environment variables
41+
.env
42+
.env.local
43+
.env.*.local
44+
45+
# Node/Frontend
46+
node_modules/
47+
dist/
48+
.next/
49+
out/
50+
51+
# Testing
52+
.pytest_cache/
53+
.coverage
54+
htmlcov/
55+
56+
# Qdrant
57+
storage/
58+
snapshots/
59+
60+
# OS
61+
.DS_Store
62+
Thumbs.db
63+
64+
# Logs
65+
*.log

‎CONTRIBUTING.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Contributing
2+
3+
## Scope
4+
5+
Dieses Repository ist als nachvollziehbarer PoC gedacht.
6+
7+
## Lokaler Ablauf
8+
9+
1. `make setup`
10+
2. `make up`
11+
3. `make smoke`
12+
4. Dokumentation aktualisieren, falls Verhalten geaendert wurde
13+
14+
## Pull Requests
15+
16+
- Kleine, fokussierte PRs
17+
- README und Beispielaufrufe mit aendern, wenn sich Schnittstellen aendern
18+
- Keine Secrets committen (`.env` bleibt lokal)

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Vitalij Bojatschkin
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎Makefile‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
.PHONY: setup up down logs smoke
2+
3+
setup:
4+
@if [ ! -f .env ]; then \
5+
cp .env.example .env; \
6+
echo "[setup] .env wurde aus .env.example erstellt. Bitte AWS Credentials eintragen."; \
7+
else \
8+
echo "[setup] .env existiert bereits."; \
9+
fi
10+
11+
up:
12+
docker compose up -d
13+
14+
down:
15+
docker compose down
16+
17+
logs:
18+
docker compose logs -f
19+
20+
smoke:
21+
@curl -fsS http://localhost:8000/health >/dev/null && echo "[smoke] API erreichbar auf :8000"
22+
@curl -fsS http://localhost:3000 >/dev/null && echo "[smoke] Frontend erreichbar auf :3000"

‎README.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
# RAG-Dokumenten-Chatbot (PoC)
2+
3+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
4+
[![GitHub](https://img.shields.io/badge/GitHub-vibtellect/rag--document--chatbot-blue?logo=github)](https://github.com/vibtellect/rag-document-chatbot)
5+
6+
DE-first README. English version: [README_EN.md](./README_EN.md)
7+
8+
## 3-Minuten-Ergebnis
9+
10+
Diese Demo liefert einen lauffaehigen RAG-Stack fuer Unternehmensdokumente:
11+
12+
`PDF/Markdown Upload -> Chunking + Embeddings -> Qdrant -> Quellenbasierte Antwort`
13+
14+
**Proof-of-Concept**: Schnell einsatzbereit, ideal zum Lernen und Experimentieren. Fuer produktiven Einsatz siehe [Naechste Schritte](#naechste-schritte).
15+
16+
## Problem
17+
18+
Wissen steckt in vielen internen Dokumenten und ist schwer auffindbar.
19+
20+
## Loesung
21+
22+
Ein FastAPI-Backend mit Qdrant und Bedrock beantwortet Fragen auf Basis hochgeladener Inhalte, inkl. Quellenhinweisen.
23+
24+
## Architektur
25+
26+
- **Frontend**: React + Vite (Web-UI fuer Upload + Chat)
27+
- **Backend**: FastAPI (Ingestion, Retrieval, LLM-Integration)
28+
- **Vector Store**: Qdrant (In-Memory oder persistent)
29+
- **Modelle**: AWS Bedrock (Claude 3.5 Sonnet + Titan Embeddings)
30+
- **Containerisierung**: Docker Compose
31+
32+
## Quickstart
33+
34+
### 1) Setup
35+
36+
```bash
37+
make setup
38+
```
39+
40+
Dann `.env` aus `.env.example` kopieren und fuellen:
41+
42+
```bash
43+
AWS_ACCESS_KEY_ID=AKIAXXXXXXXXXXXXXXXX
44+
AWS_SECRET_ACCESS_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
45+
AWS_REGION=eu-central-1
46+
```
47+
48+
### 2) Start (Docker Compose)
49+
50+
```bash
51+
make up
52+
```
53+
54+
Frontend erreichbar unter `http://localhost:3000`, API unter `http://localhost:8000`.
55+
56+
### 3) Smoke-Test
57+
58+
```bash
59+
make smoke
60+
```
61+
62+
Erwartung:
63+
- API Health `http://localhost:8000/health` erreichbar
64+
- Frontend `http://localhost:3000` erreichbar
65+
66+
### 4) Stop
67+
68+
```bash
69+
make down
70+
```
71+
72+
## Demo-Nutzung {#demo}
73+
74+
### 1) Demo-Dokumente hochladen
75+
76+
5 Unternehmensdokumente stehen in `demo-docs/` bereit:
77+
78+
```bash
79+
# Alle Demo-Dokumente hochladen
80+
for doc in demo-docs/*.md; do
81+
curl -X POST http://localhost:8000/api/upload \
82+
-F "file=@$doc" -F "tenant_id=demo"
83+
done
84+
```
85+
86+
### 2) Fragen stellen (cURL)
87+
88+
```bash
89+
# IT-Sicherheit
90+
curl -X POST http://localhost:8000/api/ask \
91+
-H "Content-Type: application/json" \
92+
-d '{"question": "Wie viele Zeichen muss ein Passwort mindestens haben?", "tenant_id": "demo"}'
93+
94+
# Reisekosten
95+
curl -X POST http://localhost:8000/api/ask \
96+
-H "Content-Type: application/json" \
97+
-d '{"question": "Wie hoch ist die Hotelkostenpauschale in Muenchen?", "tenant_id": "demo"}'
98+
99+
# Homeoffice
100+
curl -X POST http://localhost:8000/api/ask \
101+
-H "Content-Type: application/json" \
102+
-d '{"question": "Wie viele Tage pro Woche darf ich im Homeoffice arbeiten?", "tenant_id": "demo"}'
103+
104+
# Onboarding
105+
curl -X POST http://localhost:8000/api/ask \
106+
-H "Content-Type: application/json" \
107+
-d '{"question": "Was muss ich in der ersten Woche als neuer Mitarbeiter erledigen?", "tenant_id": "demo"}'
108+
```
109+
110+
### 3) UI-basiert
111+
112+
Frontend unter `http://localhost:3000` oeffnen:
113+
1. Documents hochladen (Drag-and-Drop oder Button)
114+
2. Fragen stellen im Chat-Interface
115+
3. Quellen anzeigen und validieren
116+
117+
## API-Endpunkte
118+
119+
- `POST /api/upload` (PDF oder Markdown)
120+
- `POST /api/ask`
121+
- `GET /api/documents`
122+
- `DELETE /api/documents/{doc_id}`
123+
- `GET /health`
124+
125+
## Projektstruktur
126+
127+
```text
128+
.
129+
|-- Makefile
130+
|-- docker-compose.yml
131+
|-- .env.example
132+
|-- backend/
133+
|-- frontend/
134+
`-- demo-docs/
135+
|-- it-sicherheitsrichtlinie.md
136+
|-- urlaubsregelung.md
137+
|-- onboarding-checkliste.md
138+
|-- reisekostenrichtlinie.md
139+
`-- homeoffice-regelung.md
140+
```
141+
142+
## Kosten (Richtwert)
143+
144+
Abhaengig von Tokenvolumen und Dokumentmenge, typischerweise im niedrigen zweistelligen USD-Bereich fuer kleine PoCs.
145+
146+
Bedrock-Pricing: https://aws.amazon.com/de/bedrock/pricing/
147+
148+
## Grenzen des PoC
149+
150+
- Kein Auth-/Rechtemodell
151+
- Kein Langzeit-Monitoring/Observability
152+
- Retrieval-Strategie ist bewusst einfach gehalten
153+
- Nicht fuer direkten Produktivbetrieb ausgelegt
154+
155+
## Naechste Schritte fuer Produktivbetrieb
156+
157+
1. **Sicherheit**: Secret Management, Authentifizierung/Autorisierung, TLS
158+
2. **Retrieval**: Reranking, Hybrid Search, Query-Expansion
159+
3. **Betriebsbetrieb**: Logging, Monitoring, Alerting, Datenhaltung
160+
4. **Skalierung**: Load-Balancing, Database-Backup, Disaster-Recovery
161+
162+
Siehe [SECURITY.md](./SECURITY.md) fuer Mindestanforderungen.
163+
164+
## Lizenz
165+
166+
MIT License - siehe [LICENSE](./LICENSE)
167+
168+
## Contributing
169+
170+
Contributions sind willkommen! Siehe [CONTRIBUTING.md](./CONTRIBUTING.md) fuer Details.
171+
172+
---
173+
174+
## Weitere Ressourcen
175+
176+
- **Portfolio**: [bojatschkin.de](https://bojatschkin.de) – Cloud Engineer mit KI-Integration
177+
- **Blogpost**: [RAG-Chatbot mit Bedrock – Praxiswissen aus Unternehmensdokumenten](https://bojatschkin.de/blog/rag-chatbot-bedrock?utm_source=github&utm_medium=readme&utm_campaign=rag-chatbot-demo)
178+
- **Kontakt**: Wenn du den PoC in einen produktiven Wissensassistenten mit sauberem Betriebskonzept ueberfuehren willst → [Kostenloses Erstgesprach buchen](https://bojatschkin.de?utm_source=github&utm_medium=readme&utm_campaign=rag-chatbot-contact)
179+
180+
---
181+
182+
Built by [vibtellect](https://github.com/vibtellect) – Cloud Engineering & AI Integration

0 commit comments

Comments
 (0)