SmartERP Documentation An Ashewa Technology Solutions Platform

Model Diagnostics, Inference Exceptions & Troubleshooting FAQ

Resolution runbook for GPU out-of-memory errors, tokenizer mismatches, slow inference latencies, and connectivity timeouts.

1. Overview & Technical Architecture#

Diagnostic reference for integrated custom AI model operations.

1. Diagnostic Resolution Matrix#

IssueProbable CauseCorrective Action
CUDA out of memory (OOM)Context length exceeded GPU VRAM capacity.Reduce max_model_len in server launch parameters or enable 4-bit AWQ quantization.
Inference Timeout (>30s)Server queuing behind heavy concurrent batch requests.Increase worker threads or deploy load-balanced vLLM instances behind Nginx.
Malformed Unicode Characters in AmharicClient terminal or browser font lacks Ge'ez font glyphs (Nyala/Abyssinica).Ensure system font stack includes Nyala, Abyssinica SIL, sans-serif.

2. Prerequisites & Infrastructure Requirements#

  • Runtime Environment: Python 3.12+, PostgreSQL 16 with pgvector extension.
  • Security Access Group: Ashewa AI / Administrator (Technical ID: muk_ai.group_ai_manager)
  • Hardware Profile: Minimum 16 GB System RAM (CPU inference) or NVIDIA GPU with 8+ GB VRAM.

3. Step-by-Step Configuration & Verification#

Step 1: Navigating to Model Management#

  1. Access your SmartERP instance at https://smarterp.et/odoo.
  2. Open Settings → Technical → Ashewa AI → Model Registry.
  3. Select the custom model profile.

{screenshot:90-troubleshooting-and-model-faq-step1-navigation}

Step 2: Testing Endpoint Health & Response Verification#

  1. Click the Run Diagnostic Health Check button.
  2. Verify token generation speed (tokens/sec) and latency benchmarks.
  3. Review sample response in the diagnostic console.

{screenshot:90-troubleshooting-and-model-faq-step2-verification}

4. Advanced Configuration Points#

  • Automated Tasks: muk_ai.ir_cron_model_health_monitor runs every 15 minutes.
  • Multi-Tenant Boundaries: Custom model fine-tuning adapters are strictly segregated per tenant database.

5. Comprehensive Troubleshooting Matrix#

Symptom / ErrorProbable Root CauseResolution Action
Connection refused: Model server unreachableInference daemon stopped or port blocked by firewall.Restart model service (systemctl restart vllm) and verify firewall rules.
Token limit exceeded on input promptInput context exceeded window size.Enable context truncation in model profile settings.
Last updated: 2026-10-30