init

2025-09-26 17:15:54 +08:00
commit db0e5965ec
211 changed files with 40437 additions and 0 deletions
--- a/vw-agentic-rag/docs/topics/SERVICE_SETUP.md
+++ b/vw-agentic-rag/docs/topics/SERVICE_SETUP.md
@@ -0,0 +1,138 @@
+# Agentic RAG Service Setup Guide
+
+## 🚀 Quick Start
+
+### Prerequisites
+- Python 3.11+ with `uv` package manager
+- `config.yaml` file in the root directory
+
+### Starting the Service
+
+#### Option 1: Using the startup script (Recommended)
+```bash
+# Production mode (background)
+./start_service.sh
+
+# Development mode (with auto-reload)
+./start_service.sh --dev
+```
+
+#### Option 2: Manual startup
+```bash
+# Make sure you're in the root directory with config.yaml
+cd /home/fl/code/ai-solution/agentic-rag-4
+
+# Start the service
+uv run uvicorn service.main:app --host 127.0.0.1 --port 8000
+```
+
+### Stopping the Service
+```bash
+./stop_service.sh
+```
+
+### Configuration
+
+The service expects a `config.yaml` file in the root directory. Example structure:
+
+```yaml
+# Configuration
+provider: azure  # or openai
+
+openai:
+  base_url: "${OPENAI_BASE_URL:-https://api.openai.com/v1}"
+  api_key: "${OPENAI_API_KEY}"
+  model: "gpt-4o"
+
+azure:
+  base_url: "https://your-azure-endpoint.com/..."
+  api_key: "your-azure-api-key"
+  deployment: "gpt-4o"
+  api_version: "2024-11-20"
+
+retrieval:
+  endpoint: "http://your-retrieval-endpoint.com"
+  api_key: "your-retrieval-api-key"
+
+app:
+  name: "agentic-rag"
+  memory_ttl_days: 7
+  max_tool_loops: 3
+  cors_origins: ["*"]
+  logging:
+    level: "INFO"
+
+llm:
+  rag:
+    temperature: 0.2
+    max_tokens: 4000
+    system_prompt: |
+      # Your detailed system prompt here...
+    user_prompt: |
+      <user_query>{{user_query}}</user_query>
+      # Rest of your user prompt template...
+
+logging:
+  level: "INFO"
+  format: "json"
+```
+
+### Service Endpoints
+
+Once running, the service provides:
+
+- **Health Check**: `http://127.0.0.1:8000/health`
+- **API Documentation**: `http://127.0.0.1:8000/docs`
+- **Chat API**: `http://127.0.0.1:8000/api/chat` (POST with streaming response)
+
+### Environment Variables
+
+The configuration supports environment variable substitution:
+
+- `${OPENAI_API_KEY}` - Your OpenAI API key
+- `${OPENAI_BASE_URL:-https://api.openai.com/v1}` - OpenAI base URL with default fallback
+
+### Troubleshooting
+
+#### Service won't start
+1. Check if `config.yaml` exists in the root directory
+2. Verify the configuration syntax
+3. Check if the port is already in use: `lsof -i :8000`
+4. View logs: `tail -f server.log`
+
+#### Configuration issues
+1. Ensure all required fields are present in `config.yaml`
+2. Check environment variables are set correctly
+3. Validate YAML syntax
+
+#### Performance issues
+1. Monitor logs: `tail -f server.log`
+2. Check retrieval service connectivity
+3. Verify LLM provider configuration
+
+### Development
+
+For development with auto-reload:
+```bash
+./start_service.sh --dev
+```
+
+This will watch for file changes and automatically restart the service.
+
+## 📁 File Structure
+
+```
+/home/fl/code/ai-solution/agentic-rag-4/
+├── config.yaml              # Main configuration file
+├── start_service.sh          # Service startup script
+├── stop_service.sh          # Service stop script
+├── server.log               # Service logs (when running in background)
+├── service/                 # Service source code
+│   ├── main.py             # FastAPI application
+│   ├── config.py           # Configuration handling
+│   ├── graph/              # Workflow graph
+│   ├── memory/             # Memory store
+│   ├── tools/              # Retrieval tools
+│   └── schemas/            # Data models
+└── ...
+```