From 3be8b2d8e157f4396ad6fd13b5ab959ef9352efd Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Tue, 26 Aug 2025 19:07:10 +0200 Subject: [PATCH] chore(refactor): cli -> cmd, update docs (#6148) * chore(refactor): cli -> cmd Signed-off-by: Ettore Di Giacinto * Update README Signed-off-by: Ettore Di Giacinto --------- Signed-off-by: Ettore Di Giacinto --- .goreleaser.yaml | 2 +- Makefile | 6 +- backend/python/README.md | 196 ++++++++++++++++-- {cli => cmd}/launcher/icon.go | 0 {cli => cmd}/launcher/internal/launcher.go | 0 .../launcher/internal/launcher_suite_test.go | 0 .../launcher/internal/launcher_test.go | 2 +- .../launcher/internal/release_manager.go | 0 .../launcher/internal/release_manager_test.go | 2 +- .../launcher/internal/systray_manager.go | 0 {cli => cmd}/launcher/internal/ui.go | 0 {cli => cmd}/launcher/logo.png | Bin {cli => cmd}/launcher/main.go | 2 +- {cli => cmd}/local-ai/main.go | 0 14 files changed, 181 insertions(+), 29 deletions(-) rename {cli => cmd}/launcher/icon.go (100%) rename {cli => cmd}/launcher/internal/launcher.go (100%) rename {cli => cmd}/launcher/internal/launcher_suite_test.go (100%) rename {cli => cmd}/launcher/internal/launcher_test.go (99%) rename {cli => cmd}/launcher/internal/release_manager.go (100%) rename {cli => cmd}/launcher/internal/release_manager_test.go (98%) rename {cli => cmd}/launcher/internal/systray_manager.go (100%) rename {cli => cmd}/launcher/internal/ui.go (100%) rename {cli => cmd}/launcher/logo.png (100%) rename {cli => cmd}/launcher/main.go (97%) rename {cli => cmd}/local-ai/main.go (100%) diff --git a/.goreleaser.yaml b/.goreleaser.yaml index 019f76b3c..b2e101f61 100644 --- a/.goreleaser.yaml +++ b/.goreleaser.yaml @@ -8,7 +8,7 @@ source: enabled: true name_template: '{{ .ProjectName }}-{{ .Tag }}-source' builds: - - main: ./cli/local-ai + - main: ./cmd/local-ai env: - CGO_ENABLED=0 ldflags: diff --git a/Makefile b/Makefile index 8657acdfa..819104c84 100644 --- a/Makefile +++ b/Makefile @@ -91,7 +91,7 @@ build: protogen-go install-go-tools ## Build the project $(info ${GREEN}I LD_FLAGS: ${YELLOW}$(LD_FLAGS)${RESET}) $(info ${GREEN}I UPX: ${YELLOW}$(UPX)${RESET}) rm -rf $(BINARY_NAME) || true - CGO_LDFLAGS="$(CGO_LDFLAGS)" $(GOCMD) build -ldflags "$(LD_FLAGS)" -tags "$(GO_TAGS)" -o $(BINARY_NAME) ./cli/local-ai + CGO_LDFLAGS="$(CGO_LDFLAGS)" $(GOCMD) build -ldflags "$(LD_FLAGS)" -tags "$(GO_TAGS)" -o $(BINARY_NAME) ./cmd/local-ai build-launcher: ## Build the launcher application $(info ${GREEN}I local-ai launcher build info:${RESET}) @@ -99,7 +99,7 @@ build-launcher: ## Build the launcher application $(info ${GREEN}I GO_TAGS: ${YELLOW}$(GO_TAGS)${RESET}) $(info ${GREEN}I LD_FLAGS: ${YELLOW}$(LD_FLAGS)${RESET}) rm -rf $(LAUNCHER_BINARY_NAME) || true - CGO_LDFLAGS="$(CGO_LDFLAGS)" $(GOCMD) build -ldflags "$(LD_FLAGS)" -tags "$(GO_TAGS)" -o $(LAUNCHER_BINARY_NAME) ./cli/launcher + CGO_LDFLAGS="$(CGO_LDFLAGS)" $(GOCMD) build -ldflags "$(LD_FLAGS)" -tags "$(GO_TAGS)" -o $(LAUNCHER_BINARY_NAME) ./cmd/launcher build-all: build build-launcher ## Build both server and launcher @@ -537,4 +537,4 @@ build-launcher-darwin: build-launcher --outputDir "dist/" build-launcher-linux: - cd cli/launcher && go run fyne.io/tools/cmd/fyne@latest package -os linux -icon ../../core/http/static/logo.png --executable $(LAUNCHER_BINARY_NAME)-linux && mv launcher.tar.xz ../../$(LAUNCHER_BINARY_NAME)-linux.tar.xz \ No newline at end of file + cd cmd/launcher && go run fyne.io/tools/cmd/fyne@latest package -os linux -icon ../../core/http/static/logo.png --executable $(LAUNCHER_BINARY_NAME)-linux && mv launcher.tar.xz ../../$(LAUNCHER_BINARY_NAME)-linux.tar.xz \ No newline at end of file diff --git a/backend/python/README.md b/backend/python/README.md index aacf63f43..8c7659346 100644 --- a/backend/python/README.md +++ b/backend/python/README.md @@ -1,38 +1,190 @@ -# Common commands about conda environment +# Python Backends for LocalAI -## Create a new empty conda environment +This directory contains Python-based AI backends for LocalAI, providing support for various AI models and hardware acceleration targets. -``` -conda create --name python= -y +## Overview -conda create --name autogptq python=3.11 -y +The Python backends use a unified build system based on `libbackend.sh` that provides: +- **Automatic virtual environment management** with support for both `uv` and `pip` +- **Hardware-specific dependency installation** (CPU, CUDA, Intel, MLX, etc.) +- **Portable Python support** for standalone deployments +- **Consistent backend execution** across different environments + +## Available Backends + +### Core AI Models +- **transformers** - Hugging Face Transformers framework (PyTorch-based) +- **vllm** - High-performance LLM inference engine +- **mlx** - Apple Silicon optimized ML framework +- **exllama2** - ExLlama2 quantized models + +### Audio & Speech +- **bark** - Text-to-speech synthesis +- **coqui** - Coqui TTS models +- **faster-whisper** - Fast Whisper speech recognition +- **kitten-tts** - Lightweight TTS +- **mlx-audio** - Apple Silicon audio processing +- **chatterbox** - TTS model +- **kokoro** - TTS models + +### Computer Vision +- **diffusers** - Stable Diffusion and image generation +- **mlx-vlm** - Vision-language models for Apple Silicon +- **rfdetr** - Object detection models + +### Specialized + +- **rerankers** - Text reranking models + +## Quick Start + +### Prerequisites +- Python 3.10+ (default: 3.10.18) +- `uv` package manager (recommended) or `pip` +- Appropriate hardware drivers for your target (CUDA, Intel, etc.) + +### Installation + +Each backend can be installed individually: + +```bash +# Navigate to a specific backend +cd backend/python/transformers + +# Install dependencies +make transformers +# or +bash install.sh + +# Run the backend +make run +# or +bash run.sh ``` -## To activate the environment +### Using the Unified Build System -As of conda 4.4 -``` -conda activate autogptq +The `libbackend.sh` script provides consistent commands across all backends: + +```bash +# Source the library in your backend script +source $(dirname $0)/../common/libbackend.sh + +# Install requirements (automatically handles hardware detection) +installRequirements + +# Start the backend server +startBackend $@ + +# Run tests +runUnittests ``` -The conda version older than 4.4 +## Hardware Targets -``` -source activate autogptq +The build system automatically detects and configures for different hardware: + +- **CPU** - Standard CPU-only builds +- **CUDA** - NVIDIA GPU acceleration (supports CUDA 11/12) +- **Intel** - Intel XPU/GPU optimization +- **MLX** - Apple Silicon (M1/M2/M3) optimization +- **HIP** - AMD GPU acceleration + +### Target-Specific Requirements + +Backends can specify hardware-specific dependencies: +- `requirements.txt` - Base requirements +- `requirements-cpu.txt` - CPU-specific packages +- `requirements-cublas11.txt` - CUDA 11 packages +- `requirements-cublas12.txt` - CUDA 12 packages +- `requirements-intel.txt` - Intel-optimized packages +- `requirements-mps.txt` - Apple Silicon packages + +## Configuration Options + +### Environment Variables + +- `PYTHON_VERSION` - Python version (default: 3.10) +- `PYTHON_PATCH` - Python patch version (default: 18) +- `BUILD_TYPE` - Force specific build target +- `USE_PIP` - Use pip instead of uv (default: false) +- `PORTABLE_PYTHON` - Enable portable Python builds +- `LIMIT_TARGETS` - Restrict backend to specific targets + +### Example: CUDA 12 Only Backend + +```bash +# In your backend script +LIMIT_TARGETS="cublas12" +source $(dirname $0)/../common/libbackend.sh ``` -## Install the packages to your environment +### Example: Intel-Optimized Backend -Sometimes you need to install the packages from the conda-forge channel - -By using `conda` -``` -conda install - -conda install -c conda-forge +```bash +# In your backend script +LIMIT_TARGETS="intel" +source $(dirname $0)/../common/libbackend.sh ``` -Or by using `pip` +## Development + +### Adding a New Backend + +1. Create a new directory in `backend/python/` +2. Copy the template structure from `common/template/` +3. Implement your `backend.py` with the required gRPC interface +4. Add appropriate requirements files for your target hardware +5. Use `libbackend.sh` for consistent build and execution + +### Testing + +```bash +# Run backend tests +make test +# or +bash test.sh ``` -pip install + +### Building + +```bash +# Install dependencies +make + +# Clean build artifacts +make clean ``` + +## Architecture + +Each backend follows a consistent structure: +``` +backend-name/ +├── backend.py # Main backend implementation +├── requirements.txt # Base dependencies +├── requirements-*.txt # Hardware-specific dependencies +├── install.sh # Installation script +├── run.sh # Execution script +├── test.sh # Test script +├── Makefile # Build targets +└── test.py # Unit tests +``` + +## Troubleshooting + +### Common Issues + +1. **Missing dependencies**: Ensure all requirements files are properly configured +2. **Hardware detection**: Check that `BUILD_TYPE` matches your system +3. **Python version**: Verify Python 3.10+ is available +4. **Virtual environment**: Use `ensureVenv` to create/activate environments + +## Contributing + +When adding new backends or modifying existing ones: +1. Follow the established directory structure +2. Use `libbackend.sh` for consistent behavior +3. Include appropriate requirements files for all target hardware +4. Add comprehensive tests +5. Update this README if adding new backend types diff --git a/cli/launcher/icon.go b/cmd/launcher/icon.go similarity index 100% rename from cli/launcher/icon.go rename to cmd/launcher/icon.go diff --git a/cli/launcher/internal/launcher.go b/cmd/launcher/internal/launcher.go similarity index 100% rename from cli/launcher/internal/launcher.go rename to cmd/launcher/internal/launcher.go diff --git a/cli/launcher/internal/launcher_suite_test.go b/cmd/launcher/internal/launcher_suite_test.go similarity index 100% rename from cli/launcher/internal/launcher_suite_test.go rename to cmd/launcher/internal/launcher_suite_test.go diff --git a/cli/launcher/internal/launcher_test.go b/cmd/launcher/internal/launcher_test.go similarity index 99% rename from cli/launcher/internal/launcher_test.go rename to cmd/launcher/internal/launcher_test.go index aed84836f..1b53a4c2e 100644 --- a/cli/launcher/internal/launcher_test.go +++ b/cmd/launcher/internal/launcher_test.go @@ -10,7 +10,7 @@ import ( "fyne.io/fyne/v2/app" - launcher "github.com/mudler/LocalAI/cli/launcher/internal" + launcher "github.com/mudler/LocalAI/cmd/launcher/internal" ) var _ = Describe("Launcher", func() { diff --git a/cli/launcher/internal/release_manager.go b/cmd/launcher/internal/release_manager.go similarity index 100% rename from cli/launcher/internal/release_manager.go rename to cmd/launcher/internal/release_manager.go diff --git a/cli/launcher/internal/release_manager_test.go b/cmd/launcher/internal/release_manager_test.go similarity index 98% rename from cli/launcher/internal/release_manager_test.go rename to cmd/launcher/internal/release_manager_test.go index ae42d17b3..d3309d50f 100644 --- a/cli/launcher/internal/release_manager_test.go +++ b/cmd/launcher/internal/release_manager_test.go @@ -8,7 +8,7 @@ import ( . "github.com/onsi/ginkgo/v2" . "github.com/onsi/gomega" - launcher "github.com/mudler/LocalAI/cli/launcher/internal" + launcher "github.com/mudler/LocalAI/cmd/launcher/internal" ) var _ = Describe("ReleaseManager", func() { diff --git a/cli/launcher/internal/systray_manager.go b/cmd/launcher/internal/systray_manager.go similarity index 100% rename from cli/launcher/internal/systray_manager.go rename to cmd/launcher/internal/systray_manager.go diff --git a/cli/launcher/internal/ui.go b/cmd/launcher/internal/ui.go similarity index 100% rename from cli/launcher/internal/ui.go rename to cmd/launcher/internal/ui.go diff --git a/cli/launcher/logo.png b/cmd/launcher/logo.png similarity index 100% rename from cli/launcher/logo.png rename to cmd/launcher/logo.png diff --git a/cli/launcher/main.go b/cmd/launcher/main.go similarity index 97% rename from cli/launcher/main.go rename to cmd/launcher/main.go index 0369981e3..60ba1da08 100644 --- a/cli/launcher/main.go +++ b/cmd/launcher/main.go @@ -9,7 +9,7 @@ import ( "fyne.io/fyne/v2" "fyne.io/fyne/v2/app" "fyne.io/fyne/v2/driver/desktop" - coreLauncher "github.com/mudler/LocalAI/cli/launcher/internal" + coreLauncher "github.com/mudler/LocalAI/cmd/launcher/internal" ) func main() { diff --git a/cli/local-ai/main.go b/cmd/local-ai/main.go similarity index 100% rename from cli/local-ai/main.go rename to cmd/local-ai/main.go