Documentation

NAME

Mail::MIMEDefang::ML::OpenAI - OpenAI-compatible chat completions backend for Mail::MIMEDefang::ML.

SYNOPSIS

use Mail::MIMEDefang::ML;

$Mail::MIMEDefang::ML::Config{backend}          = 'openai';
$Mail::MIMEDefang::ML::Config{openai}{base_url} = 'http://127.0.0.1:11434/v1';
$Mail::MIMEDefang::ML::Config{openai}{model}    = 'qwen3:8b';

DESCRIPTION

Talks to a self-hosted generative model through the OpenAI-compatible /chat/completions API, as served by Ollama, llama.cpp (llama-server), vLLM or LM Studio. base_url may name any host name or IP address; keep the model server's port firewalled so only the MIMEDefang host(s) can reach it (see "SECURITY" in Mail::MIMEDefang::ML).

The model is asked, at temperature 0 and in JSON mode, for the probability that the answer to each question is yes: {"is_spam":0..1,"is_phishing":0..1}. As with the GLiClass backend, a probability p >= 0.5 is a "yes" with confidence p, otherwise a "no" with confidence 1 - p. A single probability is more reliable than a separate answer/confidence pair, which models tend to get confused (e.g. "no" with confidence 0). Anything that doesn't parse as that is reported as an error, i.e. "no opinion".

CHOOSING A MODEL

Use an instruction-tuned model with at least 7-8 billion parameters (e.g. Qwen3 8B, Llama 3.1 8B, Mistral 7B, Gemma 2 9B, or larger).

Smaller models (1-4B, e.g. Qwen3 1.7B or Phi-3 mini) do produce valid answers and catch blatant spam and phishing, but in testing they judged subtler unsolicited mail, such as polite cold sales or business pitches, as ham, whatever the prompt wording and even with the full headers and authentication results available. They add little on top of SpamAssassin and are not recommended.

TIMEOUT

The default $Mail::MIMEDefang::ML::Config{timeout} of 30 seconds is sized for the encoder backends (Laya, GLiClass), which answer in well under a second on a GPU. Generative models are much slower: an 8B model takes hundreds of milliseconds per message on a GPU and several seconds, up to tens of seconds for long messages, on CPU. Increase the timeout when using this backend, e.g.:

$Mail::MIMEDefang::ML::Config{timeout} = 60;

Measure your model's worst case (e.g. with mimedefang-test-mail on a few large messages) and leave some headroom: a request that times out is treated as "no opinion".

ml_classify can wait up to timeout seconds (requests that time out are not retried, connect_retries only applies when the server can't be reached), and it runs inside filter_end together with SpamAssassin. Keep that total below the multiplexor's busy timeout (mimedefang-multiplexor -b, default 120 seconds), or busy workers get killed and the message is tempfailed, and below the MTA's milter timeouts (Postfix milter_content_timeout, Sendmail's T=E:). Raise -b as well if a large timeout is needed.

CONFIGURATION

$Mail::MIMEDefang::ML::Config{openai}: base_url (default http://127.0.0.1:11434/v1), model (required, no default), max_tokens (default 100), json_mode (default 1; set to 0 for servers that reject response_format), reasoning_effort (default none), body_head_chars and body_tail_chars (body kept, default 6000 and 1500 characters; lower them for models with a small context window or to save time on CPU), question_texts (question wording for this backend, see "CONFIGURATION" in Mail::MIMEDefang::ML).

Thinking models (Qwen3, DeepSeek-R1, gpt-oss, ...) otherwise spend the max_tokens budget on their chain of thought and return an empty answer; reasoning_effort none turns thinking off on Ollama and other servers that honour it. Set it to undef or '' to omit the parameter for servers that reject it, and raise max_tokens (e.g. 1024) for models that can't stop thinking.

SEE ALSO

Mail::MIMEDefang::ML.