diff --git a/content/docs/getting-started/_index.md b/content/docs/getting-started/_index.md index 000b72f..e5b65e6 100644 --- a/content/docs/getting-started/_index.md +++ b/content/docs/getting-started/_index.md @@ -34,7 +34,68 @@ When running, the Comind consumer: This guide will help you run the reference agent on your machine. Note — this is resource intensive and complicated to set up. It requires access to LLM and embedding servers. -### Setting up vLLM Servers +### Service Architecture + +Comind consists of two main service categories that can be run independently: + +1. **Database Services**: Neo4j graph database for storing and querying the knowledge graph +2. **Inference Services**: vLLM servers for language model inference and embeddings + +You can choose to run only the services you need using Docker Compose profiles. + +### Setting up Services with Docker Compose + +The included `docker-compose.yml` supports flexible service deployment: + +```bash +# Start only database services (default) +docker-compose up -d +# or explicitly +docker-compose --profile database up -d + +# Start only inference services +docker-compose --profile inference up -d + +# Start all services +docker-compose --profile all up -d +``` + +For easier management, use the included service script: + +```bash +# Start only database +./scripts/services.sh start database + +# Start only inference services +./scripts/services.sh start inference + +# Start all services +./scripts/services.sh start all + +# Check status +./scripts/services.sh status + +# View logs +./scripts/services.sh logs neo4j +``` + +### Database Services + +The database services include Neo4j for graph-based knowledge storage and querying. + +#### Neo4j Configuration + +- **Neo4j Browser**: http://localhost:7474 +- **Bolt Protocol**: bolt://localhost:7687 +- **Username**: neo4j +- **Password**: comind123 + +Access Neo4j shell directly: +```bash +./scripts/services.sh shell +``` + +### Inference Services (vLLM) If you have sufficient hardware (particularly a GPU with enough VRAM), you can run the LLM and embedding servers locally using Docker Compose. @@ -54,65 +115,26 @@ HF_TOKEN=your_hugging_face_token_here HUGGING_FACE_HUB_TOKEN=your_hugging_face_token_here ``` -3. Use the following `docker-compose.yml`: - -```yaml -services: - srv-llm: - image: vllm/vllm-openai:latest - runtime: nvidia - deploy: - resources: - reservations: - devices: - - capabilities: [gpu] - environment: - HF_TOKEN: ${HF_TOKEN} - HUGGING_FACE_HUB_TOKEN: ${HUGGING_FACE_HUB_TOKEN} - volumes: - - ~/.cache/huggingface:/root/.cache/huggingface - ports: - - "8002:8000" - command: > - --model microsoft/Phi-4 - --max_model_len 15000 - --guided-decoding-backend outlines - - embeddings: - image: vllm/vllm-openai:latest - runtime: nvidia - deploy: - resources: - reservations: - devices: - - capabilities: [gpu] - environment: - HUGGING_FACE_HUB_TOKEN: ${HUGGING_FACE_HUB_TOKEN} - volumes: - - ~/.cache/huggingface:/root/.cache/huggingface - ports: - - "8001:8000" - command: > - --model mixedbread-ai/mxbai-embed-xsmall-v1 - --guided-decoding-backend outlines - --trust-remote-code -``` +3. The included `docker-compose.yml` already contains the inference service configuration with the latest models and settings. -#### Running the Servers +#### Running the Inference Services -1. Start the services: +1. Start the inference services: ```bash -docker-compose up -d +docker-compose --profile inference up -d +# or use the service script +./scripts/services.sh start inference ``` -2. Check that both services are running: +2. Check that services are running: ```bash -docker-compose ps +./scripts/services.sh status ``` 3. To view logs: ```bash -docker-compose logs -f +./scripts/services.sh logs srv-llm +./scripts/services.sh logs embeddings ``` #### Using Different Models diff --git a/docker-compose.yml b/docker-compose.yml index 47370e5..e65a6eb 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,10 +1,18 @@ -# --model microsoft/Phi-3.5-mini-instruct -# --mode microsoft/Phi-4 -# --model google/gemma-3-12b-it # needs a new version of transformers +# Comind Docker Compose Configuration +# +# Usage: +# docker-compose --profile inference up # Start inference services only +# docker-compose --profile database up # Start database services only +# docker-compose --profile all up # Start all services +# docker-compose up # Start core services (database only) + services: + # === INFERENCE SERVICES === + srv-llm: image: vllm/vllm-openai:latest runtime: nvidia + profiles: ["inference", "all"] deploy: resources: reservations: @@ -25,6 +33,7 @@ services: embeddings: image: vllm/vllm-openai:latest runtime: nvidia + profiles: ["inference", "all"] deploy: resources: reservations: @@ -40,3 +49,36 @@ services: --model mixedbread-ai/mxbai-embed-xsmall-v1 --guided-decoding-backend outlines --trust-remote-code + + # === DATABASE SERVICES === + + neo4j: + image: neo4j:5.15-community + profiles: ["database", "all", ""] # Empty profile means it runs by default + environment: + NEO4J_AUTH: neo4j/comind123 + NEO4J_PLUGINS: '["apoc"]' + NEO4J_apoc_export_file_enabled: true + NEO4J_apoc_import_file_enabled: true + NEO4J_apoc_import_file_use__neo4j__config: true + NEO4J_ACCEPT_LICENSE_AGREEMENT: yes + volumes: + - neo4j_data:/data + - neo4j_logs:/logs + - neo4j_import:/var/lib/neo4j/import + - neo4j_plugins:/plugins + ports: + - "7474:7474" # HTTP + - "7687:7687" # Bolt + healthcheck: + test: ["CMD", "cypher-shell", "-u", "neo4j", "-p", "comind123", "RETURN 1"] + interval: 30s + timeout: 10s + retries: 5 + start_period: 20s + +volumes: + neo4j_data: + neo4j_logs: + neo4j_import: + neo4j_plugins: diff --git a/requirements.txt b/requirements.txt index 118c7aa..7ff31b9 100644 --- a/requirements.txt +++ b/requirements.txt @@ -34,3 +34,4 @@ typing-extensions==4.13.0 typing-inspection==0.4.0 uc-micro-py==1.0.3 websockets==13.1 +neo4j==5.26.0 diff --git a/scripts/services.sh b/scripts/services.sh new file mode 100755 index 0000000..71c717e --- /dev/null +++ b/scripts/services.sh @@ -0,0 +1,135 @@ +#!/bin/bash + +# Comind Services Management Script +# Makes it easy to start different combinations of services + +set -e + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +PROJECT_ROOT="$(dirname "$SCRIPT_DIR")" + +cd "$PROJECT_ROOT" + +show_help() { + echo "Comind Services Management" + echo "" + echo "Usage: $0 [options]" + echo "" + echo "Commands:" + echo " start Start services" + echo " stop Stop services" + echo " restart Restart services" + echo " status Show running services" + echo " logs Show logs for a service" + echo " shell Connect to Neo4j shell" + echo "" + echo "Profiles:" + echo " database Start only Neo4j database" + echo " inference Start only inference services (LLM + embeddings)" + echo " all Start all services" + echo " (no profile) Start default services (database only)" + echo "" + echo "Examples:" + echo " $0 start database # Start only Neo4j" + echo " $0 start inference # Start only inference services" + echo " $0 start all # Start everything" + echo " $0 start # Start default (database)" + echo " $0 logs neo4j # Show Neo4j logs" + echo " $0 shell # Connect to Neo4j shell" +} + +start_services() { + local profile="$1" + + if [ -z "$profile" ]; then + echo "Starting default services (database)..." + docker-compose up -d + else + echo "Starting $profile services..." + docker-compose --profile "$profile" up -d + fi + + echo "" + echo "Services started. Access points:" + if [ "$profile" = "database" ] || [ "$profile" = "all" ] || [ -z "$profile" ]; then + echo " Neo4j Browser: http://localhost:7474" + echo " Neo4j Bolt: bolt://localhost:7687" + echo " Username: neo4j, Password: comind123" + fi + if [ "$profile" = "inference" ] || [ "$profile" = "all" ]; then + echo " LLM API: http://localhost:8002" + echo " Embeddings API: http://localhost:8001" + fi +} + +stop_services() { + local profile="$1" + + if [ -z "$profile" ]; then + echo "Stopping all services..." + docker-compose down + else + echo "Stopping $profile services..." + docker-compose --profile "$profile" down + fi +} + +restart_services() { + local profile="$1" + stop_services "$profile" + start_services "$profile" +} + +show_status() { + echo "Running Comind services:" + echo "" + docker-compose ps +} + +show_logs() { + local service="$1" + if [ -z "$service" ]; then + echo "Error: Please specify a service name" + echo "Available services: neo4j, srv-llm, embeddings" + exit 1 + fi + + docker-compose logs -f "$service" +} + +neo4j_shell() { + echo "Connecting to Neo4j shell..." + echo "Use 'MATCH (n) RETURN n LIMIT 10;' to test the connection" + docker-compose exec neo4j cypher-shell -u neo4j -p comind123 +} + +# Main command handling +case "$1" in + "start") + start_services "$2" + ;; + "stop") + stop_services "$2" + ;; + "restart") + restart_services "$2" + ;; + "status") + show_status + ;; + "logs") + show_logs "$2" + ;; + "shell") + neo4j_shell + ;; + "help"|"-h"|"--help"|"") + show_help + ;; + *) + echo "Error: Unknown command '$1'" + echo "" + show_help + exit 1 + ;; +esac \ No newline at end of file