# How to Train a DeepTutor Model: A Complete Configuration Guide

> Learn how to train a DeepTutor model by fine-tuning an external LLM. This guide details the configuration steps to integrate custom models into the agent-native orchestration layer.

- Repository: [✨Data Intelligence Lab@HKU✨/DeepTutor](https://github.com/HKUDS/DeepTutor)
- Tags: how-to-guide
- Published: 2026-04-08

---

**DeepTutor does not train model weights internally; instead, you fine-tune an external LLM and register it via the model-catalog configuration to integrate custom models into the agent-native orchestration layer.**

The HKUDS/DeepTutor repository provides an agent-native orchestration system that augments large language models with tools, retrieval, and multi-step capabilities. If you want to learn how to train a DeepTutor model, you must first understand that DeepTutor itself contains no training loop or weight update mechanisms. The framework functions as a pluggable interface layer that consumes externally hosted LLM services through a unified provider abstraction.

## Understanding DeepTutor's Architecture

DeepTutor operates as an **agent-native orchestration layer** rather than a training framework. It connects to external LLM services including OpenAI, Ollama, and OpenVINO Model Server through standardized provider interfaces. The codebase contains no gradient descent logic, loss functions, or parameter optimization routines.

The system expects all **model training** to occur outside its ecosystem. Once you have a fine-tuned model served via an HTTP API, DeepTutor handles the integration through environment-specific configurations and a centralized model catalog. This architecture separates the concerns of model development from agent orchestration, allowing you to swap underlying LLMs without modifying agent logic.

## Prerequisites for Training a DeepTutor Model

Before integrating with DeepTutor, you must complete the external training pipeline. Fine-tune your base model using libraries such as Hugging Face Transformers, vLLM, or OpenVINO Model Server. Export the trained weights to a format compatible with your serving infrastructure, such as an OpenAI-compatible endpoint, Ollama model package, or OVMS model ID.

Your trained model must expose an HTTP API that implements the **LLM provider interface** expected by DeepTutor. The `OpenAIProvider` class in [`deeptutor/services/llm/providers/open_ai.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/services/llm/providers/open_ai.py) expects endpoints supporting the `/v1/chat/completions` route with standard request/response schemas. Ensure your serving infrastructure supports these protocol requirements before attempting integration.

## Configuring Your Custom Model in DeepTutor

### Step 1: Register the Model in model_catalog.json

DeepTutor discovers available models through the `ModelCatalogService`, which manages a JSON-based registry at [`data/user/model_catalog.json`](https://github.com/HKUDS/DeepTutor/blob/main/data/user/model_catalog.json). You can programmatically add your custom model using the Python API:

```python
from pathlib import Path
from deeptutor.services.config.model_catalog import ModelCatalogService

# Load (or create) the catalog

catalog_path = Path("data/user/model_catalog.json")
service = ModelCatalogService(path=catalog_path)
catalog = service.load()

# Add a new LLM profile & model

svc = "llm"
profile_id = f"{svc}-profile-myfine"
model_id = f"{svc}-model-myfine"

catalog["services"][svc]["profiles"].append(
    {"id": profile_id, "name": "My Fine‑Tuned LLM", "host": "http://localhost:8000/v1", "api_key": "none"}
)
catalog["services"][svc]["profiles"][-1].setdefault("models", []).append(
    {"id": model_id, "name": "my-fine‑tuned", "model": "my-fine-tuned"}
)

# Persist the changes

service.save(catalog)

```

The `ModelCatalogService.save()` method in [`deeptutor/services/config/model_catalog.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/services/config/model_catalog.py) handles atomic writes and validation of the catalog structure. This registration creates the necessary metadata for DeepTutor to route requests to your custom endpoint.

### Step 2: Configure Environment Variables

Runtime behavior depends on environment variables that map to your catalog entries. Copy the template from `.env.example` and specify the connection parameters:

```bash

# Copy the template and edit it

cp .env.example .env

# In .env, point to the new model

export LLM_MODEL=my-fine-tuned
export LLM_HOST=http://localhost:8000/v1
export LLM_API_KEY=none

```

The `.env.example` file documents all required variables including `LLM_MODEL`, `LLM_HOST`, and `LLM_API_KEY`. These variables override default configurations and establish the connection context for the LLM provider abstraction layer.

### Step 3: Apply the Catalog Configuration

After updating the model catalog, render the configuration into environment variables using the CLI helper:

```bash
deeptutor config apply

```

This command invokes the configuration logic in [`deeptutor_cli/config_cmd.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor_cli/config_cmd.py), which loads the current catalog, resolves the active profile, and writes the appropriate values to `.env`. Running this step ensures synchronization between the JSON registry and the runtime environment.

### Step 4: Run DeepTutor with Your Model

With the configuration applied, launch DeepTutor capabilities using the CLI entry point in [`deeptutor_cli/main.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor_cli/main.py):

```bash
deeptutor run chat "Explain the chain rule" -t rag --kb my-physics-kb

```

All downstream capabilities including `deep_solve` and `deep_question` will automatically route inference requests to your custom model endpoint. The agent orchestration logic remains agnostic to the underlying model, allowing your fine-tuned weights to power the full capability stack.

## Key Implementation Files

Understanding these source files helps debug integration issues and extend the configuration system:

- **[`deeptutor/services/config/model_catalog.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/services/config/model_catalog.py)** – Contains the `ModelCatalogService` class that loads, validates, and persists the model-catalog JSON registry.
- **[`deeptutor_cli/config_cmd.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor_cli/config_cmd.py)** – Implements the `deeptutor config apply` command that renders catalog entries into environment variables.
- **[`deeptutor/services/llm/providers/open_ai.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor/services/llm/providers/open_ai.py)** – Provides the `OpenAIProvider` class that abstracts HTTP calls to external LLM endpoints; compatible with any OpenAI-style API.
- **`.env.example`** – Template defining required environment variables for LLM connection strings and authentication.
- **[`deeptutor_cli/main.py`](https://github.com/HKUDS/DeepTutor/blob/main/deeptutor_cli/main.py)** – Central CLI entry point that initializes capabilities using the configured model profile.

## Summary

- DeepTutor functions as an orchestration layer, not a training framework, requiring external LLM fine-tuning before integration.
- Custom models integrate through the `ModelCatalogService` by registering profiles in [`model_catalog.json`](https://github.com/HKUDS/DeepTutor/blob/main/model_catalog.json) with specific host endpoints and API keys.
- Environment variables in `.env` activate specific catalog entries, with the `deeptutor config apply` CLI command automating the synchronization.
- All DeepTutor capabilities automatically use the configured model once registered, routing chat, retrieval, and reasoning tasks through your custom endpoint.
- The provider abstraction in `deeptutor/services/llm/providers/` supports OpenAI-compatible APIs, Ollama, and OpenVINO Model Server interfaces.

## Frequently Asked Questions

### Does DeepTutor support fine-tuning LLMs directly?

No, DeepTutor does not contain training code or support direct fine-tuning of model weights. The repository focuses exclusively on orchestration and tool augmentation. You must fine-tune your model using external frameworks such as Hugging Face Transformers or PyTorch, then serve the resulting weights through a compatible HTTP API that DeepTutor can consume.

### What LLM providers are compatible with DeepTutor?

DeepTutor supports any provider implementing the standard LLM interface, including OpenAI, Ollama, and OpenVINO Model Server. The `OpenAIProvider` class specifically expects endpoints compatible with the `/v1/chat/completions` schema. You can extend support by implementing additional provider classes following the pattern established in `deeptutor/services/llm/providers/`.

### How do I switch between different models in DeepTutor?

Switch models by changing the `LLM_MODEL` environment variable or modifying the active profile in [`model_catalog.json`](https://github.com/HKUDS/DeepTutor/blob/main/model_catalog.json). Run `deeptutor config apply` to update the runtime environment, then restart your DeepTutor session. The system dynamically selects the model specified in the environment without requiring code changes or reinstallation.

### Can I use a local model with DeepTutor?

Yes, you can use locally hosted models by serving them through a local HTTP endpoint such as those provided by vLLM, Ollama, or OpenVINO Model Server. Register the local endpoint (e.g., `http://localhost:8000/v1`) in the model catalog, set the appropriate environment variables, and DeepTutor will route requests to your local inference server exactly as it would to a remote API.