Waves

https://waves-docs.smallest.ai/v4.0.0
Admin
Waves is a real-time speech AI platform providing fast and accurate text-to-speech and...
Tokens:187,670
Snippets:1,703
Trust Score:8.4
Update:7 months ago
Show doc for...
Tokens:
Raw
### Install Requests Library

Source: https://waves-docs.smallest.ai/v4.0.0/content/speech-to-text/quickstart

Installs the 'requests' library, which is required for making HTTP requests to the Smallest AI API. This is a standard Python package manager command.

```bash
pip install requests
```

--------------------------------

### Install Python Websockets Dependency

Source: https://waves-docs.smallest.ai/v4.0.0/content/speech-to-text/realtime/code-examples

Installs the necessary 'websockets' library for Python to enable WebSocket communication.

```bash
pip install websockets
```

--------------------------------

### Install AWS CLI and Configure

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/kubernetes/aws/eks-setup

Installs and configures the AWS Command Line Interface, a prerequisite for interacting with AWS services. It verifies the installation and prompts for AWS credentials.

```bash
aws --version
aws configure
```

--------------------------------

### Install Python Dependencies for Plivo Telephony Example

Source: https://waves-docs.smallest.ai/v4.0.0/content/integrations/plivo

Install all necessary Python libraries required to run the Plivo telephony example. This ensures that all dependencies are met for the application to function correctly.

```bash
pip install -r requirements.txt
```

--------------------------------

### Install kubectl for Kubernetes Interaction

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/kubernetes/aws/eks-setup

Installs kubectl, the command-line tool for interacting with Kubernetes clusters. This is essential for managing the EKS cluster after creation.

```bash
brew install kubectl
```

--------------------------------

### Install Smallest AI Python SDK

Source: https://waves-docs.smallest.ai/v4.0.0/content/text-to-speech/get-voice-models-langs

Installs the Smallest AI Python SDK using pip. This is a prerequisite for using the SDK to interact with the Smallest AI platform.

```bash
pip install smallestai
```

--------------------------------

### Install Smallest AI and Pydub Dependencies (Bash)

Source: https://waves-docs.smallest.ai/v4.0.0/content/speech-to-text/pre-recorded/code-examples

Provides the command to install the necessary Python packages, 'smallestai' and 'pydub', which are required for running the audio processing and transcription examples.

```bash
pip install smallestai pydub
```

--------------------------------

### Install eksctl for EKS Cluster Management

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/kubernetes/aws/eks-setup

Installs eksctl, a command-line tool for creating and managing EKS clusters. It includes verification of the installed version.

```bash
brew install eksctl


eksctl version
```

--------------------------------

### Install Node.js WebSocket Dependency

Source: https://waves-docs.smallest.ai/v4.0.0/content/speech-to-text/realtime/code-examples

Installs the 'ws' library for Node.js, which is a popular WebSocket client and server implementation.

```bash
npm install ws
```

--------------------------------

### Test Prometheus Queries

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/kubernetes/autoscaling/metrics-setup

Access the Prometheus UI to test various PromQL queries. These examples demonstrate how to query active requests, calculate request rates over time, and retrieve histogram quantiles for request durations.

```promql
asr_active_requests
rate(asr_total_requests[5m])
histogram_quantile(0.95, asr_request_duration_seconds_bucket)
```

--------------------------------

### Install EBS CSI Driver with eksctl

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/kubernetes/aws/eks-setup

Installs the Amazon EBS CSI driver as an EKS add-on using the eksctl command-line tool. Requires cluster name, region, and add-on name.

```bash
eksctl create addon \
  --name aws-ebs-csi-driver \
  --cluster smallest-cluster \
  --region us-east-1
```

--------------------------------

### Manual Installation of NVIDIA Device Plugin for Kubernetes

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/kubernetes/aws/gpu-nodes

Provides the command to manually install the NVIDIA device plugin for Kubernetes from a raw YAML file hosted on GitHub. This plugin is essential for exposing GPU resources to Kubernetes pods.

```bash
kubectl create -f https://raw.githubusercontent.com/NVIDIA/k8s-device-plugin/v0.14.0/nvidia-device-plugin.yml
```

--------------------------------

### Install Python SDK (Bash)

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/api-reference/authentication

Command to install the Smallest AI Python SDK using pip. Ensure you have Python and pip installed on your system before running this command.

```bash
pip install smallest-client
```

--------------------------------

### Enable Multi-Instance GPU (MIG) Partitioning

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/kubernetes/aws/gpu-nodes

This bash command partitions NVIDIA A100 or A30 GPUs into smaller instances using Multi-Instance GPU (MIG). The example command partitions a GPU into 7 instances, each with 1 GPU and 5GB of memory. This allows for more granular allocation of GPU resources.

```bash
nvidia-smi mig -cgi 9,9,9,9,9,9,9 -C

```

--------------------------------

### Install stern via Homebrew

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/troubleshooting/logs-analysis

This command installs the 'stern' log tailing utility using the Homebrew package manager on macOS. Stern allows for tailing logs from multiple Kubernetes pods simultaneously.

```bash
brew install stern
```

--------------------------------

### Install Test Deployment with Helm

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/kubernetes/storage/model-storage

This bash command installs a test deployment of the smallest-self-host application using Helm. It allows for testing new models by specifying a different model URL and deploying to a separate namespace.

```bash
helm install test smallest-self-host/smallest-self-host \
  --set models.asrModelUrl="new-model-url" \
  --namespace smallest-test
```

--------------------------------

### Create IAM Policy for EFS CSI Driver

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/kubernetes/aws/eks-setup

Downloads an example IAM policy for the EFS CSI driver and creates it in AWS IAM. This policy is required for the EFS CSI driver to function.

```bash
curl -o iam-policy.json https://raw.githubusercontent.com/kubernetes-sigs/aws-efs-csi-driver/master/docs/iam-policy-example.json

aws iam create-policy \
  --policy-name AmazonEKS_EFS_CSI_Driver_Policy \
  --policy-document file://iam-policy.json
```

--------------------------------

### Install JavaScript SDK (Bash)

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/api-reference/authentication

Command to install the Smallest AI JavaScript SDK using npm. This is the package manager for Node.js and the JavaScript ecosystem.

```bash
npm install @smallest/client
```

--------------------------------

### Verify NVIDIA Device Plugin Pods

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/kubernetes/aws/eks-setup

Checks for running NVIDIA device plugin pods in the kube-system namespace. This command is used to verify the installation of the device plugin.

```bash
kubectl get pods -n kube-system | grep nvidia
```

--------------------------------

### Install NVIDIA Driver on Ubuntu

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/docker/stt/prerequisites/software-requirements

Installs the recommended NVIDIA driver on Ubuntu systems using `ubuntu-drivers`. Requires internet access and `apt` package manager. Reboots the system after installation. Includes a verification step using `nvidia-smi`.

```bash
sudo apt-get update
sudo apt-get install -y ubuntu-drivers-common

sudo ubuntu-drivers autoinstall

sudo reboot
```

--------------------------------

### Fetch Available Voices, Models, and Languages with Smallest AI Python SDK

Source: https://waves-docs.smallest.ai/v4.0.0/content/text-to-speech/get-voice-models-langs

Demonstrates how to use the Smallest AI Python SDK to fetch available languages, voices for a specific model, user-specific cloned voices, and available TTS models. It requires the SDK to be installed and the API key to be set as an environment variable.

```python
from smallestai.waves import WavesClient

def main():
    client = WavesClient(api_key="YOUR_API_KEY")
    
    # Get available languages
    languages = client.get_languages()
    print(f"Available Languages: {languages}")
    
    # Get available voices for the "lightning-v3.1" model
    voices = client.get_voices(model="lightning-v3.1")
    print(f"Available Voices (Model: 'lightning-v3.1'): {voices}")
    
    # Get user-specific cloned voices
    cloned_voices = client.get_cloned_voices()
    print(f"Available Cloned Voices: {cloned_voices}")
    
    # Get available models
    models = client.get_models()
    print(f"Available Models: {models}")

if __name__ == "__main__":
    main()
```

--------------------------------

### Install NVIDIA Container Toolkit

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/docker/stt/prerequisites/software-requirements

Installs the NVIDIA Container Toolkit for GPU access in Docker containers. Requires `apt` package manager, `curl`, and internet access. Adds the NVIDIA repository and installs the toolkit. Restarts the Docker service.

```bash
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/libnvidia-container/gpgkey | \
  sudo apt-key add -
curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

sudo systemctl restart docker
```

--------------------------------

### Generate Load for Testing

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/troubleshooting/debugging-guide

Generate artificial load against an API endpoint using the 'hey' load testing tool within a Kubernetes pod. This example targets the '/health' endpoint of the 'api-server' service for 5 minutes with 50 concurrent users.

```bash
kubectl run load-test --rm -it --image=williamyeh/hey \
  -- -z 5m -c 50 http://api-server:7100/health
```

--------------------------------

### Install Docker on Ubuntu

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/docker/stt/prerequisites/software-requirements

Installs Docker Engine, CLI, containerd.io, and Docker Compose plugin on Ubuntu systems. Requires `apt` package manager and internet access. Adds the current user to the `docker` group.

```bash
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

sudo usermod -aG docker $USER
newgrp docker
```

--------------------------------

### Smallest Python Package Example

Source: https://waves-docs.smallest.ai/v4.0.0/content/getting-started/authentication

Example of using the Smallest Python Package to retrieve available voices.

```APIDOC
## Smallest Python Package Example

### Description
Example with the Smallest Python Package to retrieve available voices.

### Method
N/A (Python Package)

### Endpoint
N/A (Python Package)

### Parameters

#### Request Body
None

### Request Example
```python
from smallestai.waves import WavesClient

# Initialize the client with your API key
client = WavesClient(api_key="YOUR_API_KEY")

# Retrieve available voices
print(f"Available Voices: {client.get_voices(model='lightning-v3.1')}")
```

### Response
#### Success Response (200)
- **voices** (list) - A list of available voices returned by the `get_voices` method.

#### Response Example
```python
# Example output from print statement:
# Available Voices: [{'id': 'en-US-Standard-C', 'name': 'Standard English (US)', 'gender': 'female', 'language': 'en-US'}]
```
```

--------------------------------

### Install Smallest Self-Host on Kubernetes

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/kubernetes/quick-start

Installs the 'smallest-self-host' Helm chart using the specified values file and namespace. This command deploys the Smallest Self-Host application onto the Kubernetes cluster.

```bash
helm install smallest-self-host smallest-self-host/smallest-self-host \
  -f values.yaml \
  --namespace smallest
```

--------------------------------

### Connect and Debug Redis

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/troubleshooting/debugging-guide

Connect to a Redis instance using kubectl exec and execute common Redis CLI commands for debugging. This includes authentication, retrieving information, checking database size, listing keys, getting a specific key's value, monitoring live commands, checking memory usage, and inspecting slow queries.

```bash
kubectl exec -it <redis-pod> -- redis-cli
AUTH your-password
INFO
DBSIZE
KEYS *
GET some_key
MONITOR
INFO memory
SLOWLOG GET 10
```

--------------------------------

### Start Docker Services (Bash)

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/docker/stt/quick-start

Launches all defined services in the docker-compose.yml file in detached mode (-d). This command starts the entire Smallest Self-Host Speech-to-Text deployment.

```bash
docker compose up -d
```

--------------------------------

### Standalone Cluster Autoscaler Installation with Helm

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/kubernetes/autoscaling/cluster-autoscaler

This bash command installs the Cluster Autoscaler using its official Helm repository. It adds the repository, updates it, and then installs the 'cluster-autoscaler' chart into the 'kube-system' namespace, configuring it with cluster name, AWS region, and an IAM role ARN for EKS.

```bash
helm repo add autoscaler https://kubernetes.github.io/autoscaler
helm repo update

helm install cluster-autoscaler autoscaler/cluster-autoscaler \
  --namespace kube-system \
  --set autoDiscovery.clusterName=smallest-cluster \
  --set awsRegion=us-east-1 \
  --set rbac.serviceAccount.annotations."eks\.amazonaws\.com/role-arn"=arn:aws:iam::ACCOUNT_ID:role/cluster-autoscaler-role

```

--------------------------------

### Check Docker Version

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/docker/stt/prerequisites/software-requirements

Verifies the installed Docker Engine version. Requires Docker to be installed on the system. Outputs the Docker version string.

```bash
docker --version
```

--------------------------------

### Watch and Filter Kubernetes Events

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/troubleshooting/debugging-guide

Monitor Kubernetes events in real-time using 'kubectl get events --watch'. This also includes examples for filtering events by type (e.g., Warning) and sorting them by their last timestamp.

```bash
kubectl get events -n smallest --watch
kubectl get events -n smallest --field-selector type=Warning
kubectl get events -n smallest --sort-by='.lastTimestamp'
```

--------------------------------

### Transcribe Audio with cURL

Source: https://waves-docs.smallest.ai/v4.0.0/content/speech-to-text/quickstart

Shows how to transcribe an audio file using the cURL command-line tool. This method sends a POST request to the API endpoint, including the API key in the Authorization header and the audio file as binary data. Requires the SMALLEST_API_KEY environment variable.

```bash
curl --request POST \
  --url "https://waves-api.smallest.ai/api/v1/pulse/get_text?language=en" \
  --header "Authorization: Bearer $SMALLEST_API_KEY" \
  --header "Content-Type: audio/wav" \
  --data-binary "@audio.wav"
```

--------------------------------

### Example Log Messages for Smallest AI Startup

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/docker/tts/services-overview

Key log messages indicating the successful detection of a GPU, model loading, warmup completion, and server readiness.

```log
✓ GPU detected: NVIDIA A10 (24GB)
✓ Model loaded successfully
✓ Warmup completed in 3.2s
✓ Server ready on port 8876
```

--------------------------------

### Transcribe Audio with Python

Source: https://waves-docs.smallest.ai/v4.0.0/content/speech-to-text/quickstart

Demonstrates how to transcribe an audio file using Python and the 'requests' library. It sends a POST request to the API endpoint with the audio file and retrieves the transcription from the JSON response. Requires the SMALLEST_API_KEY environment variable.

```python
import os
import requests

API_KEY = os.environ.get("SMALLEST_API_KEY")

response = requests.post(
    "https://waves-api.smallest.ai/api/v1/pulse/get_text",
    params={"model": "pulse", "language": "en"},
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "audio/wav",
    },
    data=open("audio.wav", "rb").read(),
    timeout=120
)

result = response.json()
print(result["transcription"])
```

--------------------------------

### Set Environment Variables for API Credentials

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/api-reference/examples

Demonstrates how to set environment variables for API credentials, specifically `LICENSE_KEY` and `API_URL`. This is a best practice to avoid hardcoding sensitive information directly in the code.

```bash
export LICENSE_KEY="your-license-key"
export API_URL="https://api.example.com"

```

--------------------------------

### Describe GPU Node (Kubectl)

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/kubernetes/aws/eks-setup

This command describes a specific GPU node, providing detailed information that can help diagnose why it might not be ready.

```bash
kubectl describe node <gpu-node-name>
```

--------------------------------

### Redis Configuration Options (YAML)

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/docker/tts/services-overview

Demonstrates various YAML configurations for setting up Redis, including default embedded setup, persistence, authentication, and external instance connection.

```yaml
redis:
  image: redis:latest
  ports:
    - "6379:6379"
```

```yaml
redis:
  image: redis:latest
  command: redis-server --appendonly yes
  volumes:
    - redis-data:/data
```

```yaml
redis:
  image: redis:latest
  command: redis-server --requirepass ${REDIS_PASSWORD}
```

```yaml
environment:
  REDIS_URL: redis://external-host:6379
```

--------------------------------

### Basic Go Client for Smallest AI API

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/api-reference/examples

A Go client implementation for transcribing audio using the Smallest AI API. It defines request and response structures, a client with an HTTP transport, and a main function demonstrating its usage. Requires setting the LICENSE_KEY environment variable.

```go
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
    "os"
    "time"
)

type TranscriptionRequest struct {
    URL       string `json:"url"`
    Punctuate bool   `json:"punctuate,omitempty"`
    Language  string `json:"language,omitempty"`
}

type TranscriptionResult struct {
    RequestID  string  `json:"request_id"`
    Text       string  `json:"text"`
    Confidence float64 `json:"confidence"`
    Duration   float64 `json:"duration"`
}

type SmallestClient struct {
    APIUrl     string
    LicenseKey string
    HTTPClient *http.Client
}

func NewClient(apiURL, licenseKey string) *SmallestClient {
    return &SmallestClient{
        APIUrl:     apiURL,
        LicenseKey: licenseKey,
        HTTPClient: &http.Client{Timeout: 5 * time.Minute},
    }
}

func (c *SmallestClient) Transcribe(req TranscriptionRequest) (*TranscriptionResult, error) {
    jsonData, err := json.Marshal(req)
    if err != nil {
        return nil, err
    }
    
    httpReq, err := http.NewRequest("POST", c.APIUrl+"/v1/listen", bytes.NewBuffer(jsonData))
    if err != nil {
        return nil, err
    }
    
    httpReq.Header.Set("Authorization", "Token "+c.LicenseKey)
    httpReq.Header.Set("Content-Type", "application/json")
    
    resp, err := c.HTTPClient.Do(httpReq)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    
    if resp.StatusCode != http.StatusOK {
        body, _ := ioutil.ReadAll(resp.Body)
        return nil, fmt.Errorf("API error: %s", string(body))
    }
    
    var result TranscriptionResult
    if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
        return nil, err
    }
    
    return &result, nil
}

func main() {
    client := NewClient(
        "http://localhost:7100",
        os.Getenv("LICENSE_KEY"),
    )
    
    result, err := client.Transcribe(TranscriptionRequest{
        URL:       "https://example.com/audio.wav",
        Punctuate: true,
        Language:  "en",
    })
    
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }
    
    fmt.Printf("Transcription: %s\n", result.Text)
    fmt.Printf("Confidence: %.2f\n", result.Confidence)
}

```

--------------------------------

### GET /api/v1/lightning-v3.1/get_voices

Source: https://waves-docs.smallest.ai/v4.0.0/content/getting-started/authentication

Example API request to retrieve available voices using curl.

```APIDOC
## GET /api/v1/lightning-v3.1/get_voices

### Description
Test the API with this curl command by replacing `YOUR_API_KEY` with your actual key:

### Method
GET

### Endpoint
`https://waves-api.smallest.ai/api/v1/lightning-v3.1/get_voices`

### Parameters

#### Query Parameters
- **model** (string) - Optional - Specifies the model to use for retrieving voices.

#### Request Body
None

### Request Example
```bash
curl 'https://waves-api.smallest.ai/api/v1/lightning-v3.1/get_voices?model=lightning-v3.1' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

### Response
#### Success Response (200)
- **voices** (array) - A list of available voices.
  - **id** (string) - The unique identifier for the voice.
  - **name** (string) - The name of the voice.
  - **gender** (string) - The gender of the voice.
  - **language** (string) - The language of the voice.

#### Response Example
```json
{
  "voices": [
    {
      "id": "en-US-Standard-C",
      "name": "Standard English (US)",
      "gender": "female",
      "language": "en-US"
    }
  ]
}
```
```

--------------------------------

### Install Docker on CentOS/RHEL

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/docker/stt/prerequisites/software-requirements

Installs Docker Engine, CLI, containerd.io, and Docker Compose plugin on CentOS/RHEL systems. Requires `yum` package manager and internet access. Starts and enables the Docker service. Adds the current user to the `docker` group.

```bash
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo \
  https://download.docker.com/linux/centos/docker-ce.repo

sudo yum install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

sudo systemctl start docker
sudo systemctl enable docker

sudo usermod -aG docker $USER
newgrp docker
```

--------------------------------

### Port-forward Prometheus

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/kubernetes/autoscaling/metrics-setup

This command forwards the Prometheus port to your local machine, allowing you to access the Prometheus UI. It requires kubectl to be installed and configured to connect to your Kubernetes cluster.

```bash
kubectl port-forward -n default svc/smallest-prometheus-stack-prometheus 9090:9090
```

--------------------------------

### Verify EFS CSI Driver Pods

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/kubernetes/aws/eks-setup

Checks for running EFS CSI controller pods in the kube-system namespace. This verifies the installation of the EFS CSI driver.

```bash
kubectl get pods -n kube-system -l app=efs-csi-controller
```

--------------------------------

### Verify EBS CSI Driver Pods

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/kubernetes/aws/eks-setup

Checks for running EBS CSI controller pods in the kube-system namespace. This verifies the installation of the EBS CSI driver.

```bash
kubectl get pods -n kube-system -l app=ebs-csi-controller
```

--------------------------------

### Startup Issues Checklist: Pod Debugging

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/troubleshooting/debugging-guide

A checklist for diagnosing startup issues in Kubernetes pods. It includes commands to describe pods to check events, verify secrets, inspect node resource allocation, and retrieve logs from all containers within a pod.

```bash
kubectl describe pod <pod> | grep -A 10 "Events"
kubectl get secrets -n smallest
kubectl describe secret <secret-name>
kubectl describe node <node> | grep "Allocated resources" -A 10
kubectl logs <pod> --all-containers=true
```

--------------------------------

### Get ServiceMonitor

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/kubernetes/autoscaling/metrics-setup

This command retrieves the ServiceMonitor resources in the 'smallest' namespace. ServiceMonitors are Kubernetes custom resources used by Prometheus Operator to configure Prometheus to scrape metrics from services.

```bash
kubectl get servicemonitor -n smallest
```

--------------------------------

### Initialize and Use Python SDK (Python)

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/api-reference/authentication

Example of initializing the Smallest AI Python client and using it to transcribe an audio file from a URL. This snippet demonstrates basic SDK usage for transcription.

```python
from smallest import Client

client = Client(
    api_url="http://localhost:7100",
    license_key="your-license-key-here"
)

result = client.transcribe_url("https://example.com/audio.wav")
print(result.text)
```

--------------------------------

### Transcription Response with Timestamps (JSON)

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/troubleshooting/common-issues

Example of a transcription response that includes word-level timestamps. Each word object contains the transcribed text, start time, and end time.

```json
{
  "words": [
    {"word": "Hello", "start": 0.0, "end": 0.5}
  ]
}
```

--------------------------------

### Basic Audio Transcription with Node.js

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/api-reference/examples

This Node.js example demonstrates how to transcribe audio from a given URL using the Smallest AI API. It utilizes the 'axios' library for making HTTP requests and requires a LICENSE_KEY environment variable. The function returns transcription text and confidence score.

```javascript
const axios = require('axios');

const LICENSE_KEY = process.env.LICENSE_KEY;
const API_URL = 'http://localhost:7100';

async function transcribeAudio(audioUrl) {
  try {
    const response = await axios.post(
      `${API_URL}/v1/listen`,
      { url: audioUrl },
      {
        headers: {
          'Authorization': `Token ${LICENSE_KEY}`,
          'Content-Type': 'application/json'
        }
      }
    );
    
    return response.data;
  } catch (error) {
    console.error('Transcription failed:', error.response?.data || error.message);
    throw error;
  }
}

transcribeAudio('https://example.com/audio.wav')
  .then(result => {
    console.log('Transcription:', result.text);
    console.log('Confidence:', result.confidence);
  });
```

--------------------------------

### Preprocess Audio for Transcription

Source: https://waves-docs.smallest.ai/v4.0.0/content/speech-to-text/realtime/troubleshooting

Provides a Python example for preprocessing audio data before streaming it for transcription. It includes normalization and conversion to `int16` format, which are common requirements for speech-to-text services.

```python
# Normalize and clean audio before streaming
audio = audio / np.abs(audio).max() * 0.95  # Normalize
audio = audio.astype(np.int16)  # Convert to int16
```

--------------------------------

### Initialize and Use JavaScript SDK (JavaScript)

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/api-reference/authentication

Example of initializing the Smallest AI JavaScript client and using it to transcribe an audio file from a URL. This snippet demonstrates basic SDK usage for transcription in a JavaScript environment.

```javascript
import { SmallestClient } from '@smallest/client';

const client = new SmallestClient({
  apiUrl: 'http://localhost:7100',
  licenseKey: 'your-license-key-here'
});

const result = await client.transcribeUrl('https://example.com/audio.wav');
console.log(result.text);
```

--------------------------------

### Get Previous Kubernetes Pod Logs

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/troubleshooting/debugging-guide

Retrieves logs from a previous instance of a Kubernetes pod that may have crashed and restarted. This is crucial for diagnosing issues that caused the pod to terminate.

```bash
kubectl logs <pod-name> --previous
kubectl logs <pod-name> -c <container-name> --previous
```

--------------------------------

### Basic Audio Transcription with Python

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/api-reference/examples

This Python script demonstrates how to perform basic audio transcription by sending an audio file URL to the Smallest Self-Host API. It requires a license key and the API endpoint URL. The function returns the transcribed text and confidence score.

```python
import requests
import os

LICENSE_KEY = os.getenv("LICENSE_KEY")
API_URL = "http://localhost:7100"

def transcribe_audio(audio_url):
    response = requests.post(
        f"{API_URL}/v1/listen",
        headers={
            "Authorization": f"Token {LICENSE_KEY}",
            "Content-Type": "application/json"
        },
        json={"url": audio_url}
    )
    
    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"Transcription failed: {response.text}")

result = transcribe_audio("https://example.com/audio.wav")
print(f"Transcription: {result['text']}")
print(f"Confidence: {result['confidence']}")
```

--------------------------------

### Kubernetes Detailed Pod Diagnostics

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/kubernetes/k8s-troubleshooting

Use these bash commands to get detailed information about a specific pod, view its logs (including previous instances), or stream logs from a particular container.

```bash
kubectl describe pod <pod-name> -n smallest
kubectl logs <pod-name> -n smallest
kubectl logs <pod-name> -n smallest --previous
kubectl logs <pod-name> -c <container-name> -n smallest -f
```

--------------------------------

### Async Transcription with Webhook in Python (Flask)

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/api-reference/examples

This Python example uses Flask to set up a webhook endpoint that receives transcription results asynchronously from Smallest Self-Host. It demonstrates submitting an audio file for processing and handling completion or failure notifications via a callback URL.

```python
from flask import Flask, request, jsonify
import requests
import os

app = Flask(__name__)

LICENSE_KEY = os.getenv("LICENSE_KEY")
API_URL = "http://localhost:7100"

@app.route('/webhook/transcription', methods=['POST'])
def transcription_webhook():
    data = request.json
    job_id = data['job_id']
    status = data['status']
    
    if status == 'completed':
        result = data['result']
        print(f"Job {job_id} completed: {result['text']}")
    elif status == 'failed':
        print(f"Job {job_id} failed: {data['error']}")
    
    return jsonify({"received": True})

def submit_async_transcription(audio_url):
    response = requests.post(
        f"{API_URL}/v1/listen",
        headers={
            "Authorization": f"Token {LICENSE_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "url": audio_url,
            "callback_url": "https://myapp.com/webhook/transcription"
        }
    )
    
    return response.json()

if __name__ == '__main__':
    job = submit_async_transcription("https://example.com/long-audio.mp3")
    print(f"Job submitted: {job['job_id']}")
    
    app.run(port=5000)
```

--------------------------------

### Query Prometheus Metrics

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/troubleshooting/debugging-guide

Access Prometheus metrics by port-forwarding the Prometheus service and then querying specific metrics through the Prometheus UI. Examples include 'asr_active_requests', 'rate(asr_total_requests[5m])', and 'asr_gpu_utilization'.

```bash
kubectl port-forward -n default svc/smallest-prometheus-stack-prometheus 9090:9090
# Then access http://localhost:9090 and run queries like:
asr_active_requests
rate(asr_total_requests[5m])
asr_gpu_utilization
```

--------------------------------

### Launch a Debug Container

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/kubernetes/k8s-troubleshooting

Start a temporary debug container with a specified image within the same network namespace as a target pod. This allows for isolated debugging without affecting the original application container.

```bash
kubectl debug <pod-name> -n smallest -it --image=ubuntu -- bash
```

--------------------------------

### Enable NVIDIA GPU Operator with Helm

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/kubernetes/aws/eks-setup

Enables the NVIDIA GPU Operator by setting 'gpu-operator.enabled' to true in the values.yaml file for Helm deployments. This is the recommended method for installing the NVIDIA device plugin.

```yaml
gpu-operator:
  enabled: true
```

--------------------------------

### Install Evaluation Toolkit (Bash)

Source: https://waves-docs.smallest.ai/v4.0.0/content/speech-to-text/benchmarks/evaluation-walkthrough

Installs the necessary Python packages for evaluating STT models. This includes the `smallestai` client for Pulse STT, `jiwer` for Word Error Rate (WER) and Character Error Rate (CER) computation, and `whisper-normalizer` for text normalization.

```bash
pip install smallestai jiwer whisper-normalizer pandas
```

--------------------------------

### Example .env File for Docker Configuration

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/docker/tts/configuration

Provides a complete example of a .env file used for configuring Dockerized applications. It includes settings for license keys, ports, Redis connection details, GPU device ID, and voice parameters.

```bash
LICENSE_KEY=your-license-key-here

API_SERVER_PORT=7100
TTS_PORT=8876

REDIS_HOST=redis
REDIS_PORT=6379

GPU_DEVICE_ID=0

DEFAULT_VOICE=default
VOICE_SPEED=1.0
```

--------------------------------

### Get EBS CSI Driver Pod Logs (Kubectl)

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/kubernetes/aws/eks-setup

This command retrieves logs from the EBS CSI driver pods, which can provide detailed error messages for troubleshooting volume mounting issues.

```bash
kubectl logs -n kube-system -l app=ebs-csi-controller
```

--------------------------------

### Get Node Allocatable Resources (Kubectl & JQ)

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/kubernetes/aws/eks-setup

This command retrieves the allocatable resources for all nodes in the cluster using kubectl and jq, helping to diagnose pod pending issues due to capacity.

```bash
kubectl get nodes -o json | jq '.items[].status.allocatable'
```

--------------------------------

### Lightning ASR Startup Log Messages

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/docker/stt/services-overview

Illustrates typical log messages observed during the startup sequence of Lightning ASR. These logs indicate GPU detection, model download status, model loading, warmup completion, and server readiness.

```log
✓ GPU detected: NVIDIA A10 (24GB)
✓ Downloading model from URL...
✓ Model loaded successfully (5.2GB)
✓ Warmup completed in 3.2s
✓ Server ready on port 2233
```

--------------------------------

### Troubleshoot GPU Accessibility Issues

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/kubernetes/k8s-troubleshooting

Steps to resolve 'No CUDA-capable device' or 'GPU not found' errors. This involves verifying GPU availability on the node, checking the NVIDIA device plugin, and ensuring correct drivers are installed.

```bash
kubectl describe node <node-name> | grep nvidia.com/gpu
kubectl get pods -n kube-system -l name=nvidia-device-plugin
kubectl delete pod -n kube-system -l name=nvidia-device-plugin
```

--------------------------------

### Debug Kubernetes Pod with Interactive Container

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/troubleshooting/debugging-guide

Starts an interactive debugging session within a Kubernetes pod by launching a new container with specified tools. The `--target` flag allows specifying which existing container to attach to.

```bash
kubectl debug <pod-name> -it --image=ubuntu --target=<container-name>
```

--------------------------------

### Verify Prometheus Adapter Configuration

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/kubernetes/autoscaling/metrics-setup

Inspect the configuration map for the Prometheus Adapter in the 'kube-system' namespace. This allows you to check the adapter's settings and ensure it's correctly configured to expose custom metrics.

```bash
kubectl get configmap prometheus-adapter -n kube-system -o yaml
```

--------------------------------

### Basic Text-to-Speech Synthesis with Smallest AI Python SDK

Source: https://waves-docs.smallest.ai/v4.0.0/content/text-to-speech/quickstart

Demonstrates how to use the Smallest AI Python SDK to convert text to speech. This example requires an API key and saves the output to an 'output.wav' file. It allows customization of sample rate and speed.

```python
from smallestai.waves import WavesClient

def main():
    client = WavesClient(api_key="YOUR_API_KEY")
    audio = client.synthesize(
        "Modern problems require modern solutions.",
        sample_rate=24000,
        speed=1.0
    )
    with open("output.wav", "wb") as f:
        f.write(audio)

if __name__ == "__main__":
    main()
```

--------------------------------

### Parse JSON Logs with jq in Kubernetes

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/troubleshooting/debugging-guide

Uses the `jq` command-line JSON processor to filter and extract information from JSON-formatted Kubernetes logs. Examples include selecting logs by level, filtering by duration, and extracting message fields.

```bash
kubectl logs <pod> | jq 'select(.level=="error")'
kubectl logs <pod> | jq 'select(.duration > 1000)'
kubectl logs <pod> | jq '.message' -r
```

--------------------------------

### Profile Application Performance with py-spy

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/troubleshooting/debugging-guide

Installs `py-spy` within a Kubernetes pod and uses it to profile Python application performance, such as viewing active Python processes and their resource usage. It also shows how to check memory information from `/proc`.

```bash
kubectl exec -it <pod> -- sh -c 'apt-get update && apt-get install -y python3-pip && pip3 install py-spy'

kubectl exec -it <pod> -- py-spy top --pid 1

kubectl exec -it <pod> -- sh -c 'cat /proc/1/status | grep -i mem'
```

--------------------------------

### Verify NVIDIA Driver on Node (Bash)

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/kubernetes/aws/gpu-nodes

Connects to a specific Kubernetes node using `kubectl debug` and installs `nvidia-utils` to verify the NVIDIA driver. This helps in troubleshooting cases where GPUs are not detected or functioning correctly.

```bash
kubectl debug node/<node-name> -it --image=ubuntu
apt-get update && apt-get install -y nvidia-utils
nvidia-smi
```

--------------------------------

### Create Project Directory (Bash)

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/docker/stt/quick-start

Creates a new directory for the Smallest Self-Host deployment and navigates into it. This is the first step in setting up the project environment.

```bash
mkdir -p ~/smallest-self-host
cd ~/smallest-self-host
```

--------------------------------

### Transcribe Audio with Speaker Diarization

Source: https://waves-docs.smallest.ai/v4.0.0/content/on-prem/api-reference/endpoints/transcription

This example demonstrates how to transcribe audio while also identifying different speakers. It requires an audio URL and the desired number of speakers. The response provides the transcribed text segmented by speaker, along with their start and end times.

```json
{
  "url": "https://example.com/conversation.wav",
  "diarize": true,
  "num_speakers": 2
}
```
Tokens:
Raw