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.