Configure a decision model in Discourse AI

Documentation Site Management
,

AI-generated summary

This guide details how to configure and test a decision model in Discourse AI using the hosted D3 service. Decision models are distinct from language models; they classify input (yes/no, choice, or score) rather than generating conversational text. Configuration requires Administrator access, the discourse_ai_enabled flag, and a valid credential for the decision endpoint. Note that a Workflows plugin or separate language model is not required solely for configuration and testing.

To begin, administrators should create an API key via the D3 Decision API. The D3 service is free but may use submitted data for training and evaluation, so it is strictly recommended to use invented, non-confidential examples for testing. Once the key is obtained, it must be saved in Admin → Plugins → AI → Credentials under a descriptive name.

The guide explains that decision models are used in specific features like sentiment analysis, emotion detection, and combined-search intent. These features have their own prerequisites and settings (e.g., ai_sentiment_enabled, ai_sentiment_emotion_enabled, and ai_ask_ai_search_intent_decision_model). Configuring the model does not automatically enable these features; administrators must explicitly activate them. The D3 example should only be used with synthetic data unless the provider’s policies are reviewed and approved for real forum content.

A troubleshooting section addresses common issues:

  • Missing Models: Ensure Discourse AI is enabled and check the unified Models interface.
  • Authentication Failures: Verify the correct credential is selected.
  • HTTP/Response Errors: Check the endpoint URL, protocol, and model identifier.
  • Image Failures: Ensure the endpoint supports image input or disable “Supports image input” for text-only models.
  • No Action on Forum: Remember that testing does not activate features; you must save the connection and configure the consuming feature separately.

For debugging, admins can review request details in Admin → Plugins → AI → Logs, but must treat logs as sensitive and avoid pasting credentials or private data in support forums. Additional resources and links to related documentation are provided at the end of the post.

1

:bookmark: This guide explains how to configure and test a decision model in Discourse AI, using the hosted D3 service as an example.

:person_raising_hand: Required user level: Administrator

A decision model classifies an input instead of writing a conversational answer. You can use its structured results in supported Discourse AI features and workflows.

Discourse supports three question types:

Type Result
Yes or no A probability between 0 and 1
Choice A selected option, probabilities and confidence
Score A score across ordered levels, with probabilities and confidence

A decision model is separate from the language models used for AI bot replies, summaries and Helper. Configuring one does not replace your language model or automatically enable a feature.

Before you start

You need:

  • Discourse AI enabled through discourse_ai_enabled.
  • An administrator account.
  • A compatible decision-model endpoint and any credential it requires.

You don’t need the Workflows plugin or a separate language model to configure and test a decision model. A workflow requires the Workflows plugin; other features have their own prerequisites.

1. Obtain a credential for the hosted D3 example

The D3 Decision API offers free hosted access with an API key. Review its terms and privacy notice before creating a key. Creating a key requires accepting the terms, including the age requirement. No account is required.

:warning: The hosted D3 service may store submitted text, images and responses, use them for model training and evaluation, and publish de-identified data. No request header disables this. Use invented examples for testing. Don’t connect private, confidential or regulated forum content to this service.

  1. Open the D3 service and use its API-key creation control.
  2. Copy the key when it is displayed. The service only shows it once.
  3. In Discourse, open Admin → Plugins → AI → Credentials.
  4. Click “New credential”.
  5. Enter a descriptive name and paste the key into “Value”.
  6. Click “Save”.

See Managing AI credentials for credential rotation and deletion. Keep the key out of posts, screenshots and client-side code.

Free access is subject to the provider’s quotas, terms and availability. Check the provider documentation for current limits rather than treating it as an unlimited service.

2. Add the decision model

  1. Open Admin → Plugins → AI → Models, or visit /admin/plugins/discourse-ai/ai-models.
  2. Click “New model”.
  3. Choose “Decision model”.
  4. Find the “d3” template and click “Set up”.

Decision model templates with the d3 option
Decision model templates with the d3 option980×760 52 KB

The template is a starting point, not a provisioned service. It leaves the endpoint URL empty. Its description refers to self-hosting, but you can supply a compatible hosted endpoint.

  1. Fill in the following fields:
Field Hosted D3 example
Name D3 documentation test, or another descriptive display name
Provider “System One”
Model vllm-sr/d3-ultra
Endpoint URL https://decision.vllm-sr.ai/v1/systemone
Credential The credential you created in the previous section
Custom headers Leave empty for this example
Supports image input Enable for this model if you want to test image support

Use the complete inference URL. Discourse sends requests to the URL you enter; it doesn’t append /v1/systemone for you.

The preset’s vllm-sr/d3 model name is an alias at this hosted service. Using the explicit vllm-sr/d3-ultra identifier makes the example’s model choice clear. Check the provider’s model list if an identifier becomes unavailable.

D3 configuration with a named credential and image input enabled
D3 configuration with a named credential and image input enabled980×860 33.6 KB

For other providers, choose their matching template and supply their endpoint, model identifier and credential. A System One endpoint is not an OpenAI Chat Completions endpoint.

3. Test and save the connection

  1. Click “Run test”. This tests the current form values, including unsaved changes.
  2. Check the result below the form.

The built-in test sends the invented greeting “Hello! How are you doing today?” and asks whether it is a greeting. If “Supports image input” is enabled, it also sends a generated red square and checks the image response.

A successful result looks like this:

Successful D3 connection test
Successful D3 connection test980×920 38 KB

The displayed percentage is the greeting’s yes probability, rounded to a whole percentage. Success confirms a valid response and, when enabled, a basic image check. The test does not require a minimum greeting probability, so success is not an accuracy rating or a guarantee about your own classification tasks.

  1. Click “Submit” to save the model. “Run test” alone does not save it.
  2. Confirm that Discourse shows “Decision model saved”. The model is available from the Models list for later editing.

Testing makes a real request to the configured provider and creates local AI audit records. Other providers may charge for requests.

Example classification result

In a synthetic test through Discourse’s decision-model client, the hosted D3 model received this invented message:

Hello! Thank you for helping me today.

The request asked three questions about the same message. These are the actual returned results, rounded for readability:

Question Choices or levels Result
Is the message a greeting? Yes or no Yes probability: 99.30%
What is the main purpose of the message? greeting, billing, technical support greeting, with probability 99.999%
How polite is the message? rude, neutral, polite polite, with probability 99.924%

These are classification results, not a generated reply. A consuming feature can use such a result to choose what happens next. This test called the decision-model client directly; it did not activate a workflow, route a post or enable sentiment analysis. The admin “Run test” button runs the fixed greeting and optional image checks described above, not these three custom questions. Results on one invented message do not establish accuracy on your forum’s content.

4. Assign the model to a supported feature

Saving the connection does not send your forum content for classification. You must separately select the model in a consuming feature.

For this hosted D3 example, leave consumers unconfigured. Enabling one can send real forum content or search queries to the provider. Permission to run synthetic tests does not cover that data use.

Use case Where the model is selected
Workflow classification The “Classify” node in Discourse Workflows
Sentiment classification Set ai_sentiment_sentiment_classification_strategy to decision_model, then select the model in ai_sentiment_sentiment_decision_model
Emotion classification Set ai_sentiment_emotion_classification_strategy to decision_model, then select the model in ai_sentiment_emotion_decision_model
Experimental combined-search intent Select it in ai_ask_ai_search_intent_decision_model when the combined-search upcoming change is available and enabled

Each feature also needs its own enablement and configuration. Sentiment uses ai_sentiment_enabled; emotion uses ai_sentiment_emotion_enabled. Their model selectors appear after the feature is enabled and its classification strategy is set to decision_model. A search-intent decision model helps select the search experience; it does not generate the AI answer.

For the hosted D3 example, stop after the synthetic connection test unless your intended data use complies with the provider’s policy. Use an appropriately reviewed provider or self-hosted endpoint for content you cannot share under those terms.

Troubleshooting

Problem What to check
You can’t find decision models Check that Discourse AI is enabled and your release includes decision-model support. In the unified interface, use Models, not a separate Decision models tab.
Authentication fails Select the correct credential. The D3 hosted service requires a key even though access is free.
The endpoint returns an HTTP error or invalid response Check the complete endpoint URL, provider protocol and model identifier. Review the provider status and error message.
A provider limit is reached Follow its retry guidance and quotas. Don’t create additional keys to bypass limits.
The image test fails Check that the selected model and endpoint support images. Disable “Supports image input” for a text-only endpoint and run the test again.
The test passes, but nothing happens on the forum Save the connection, then configure a supported consuming feature. Testing does not activate it.

For request details, open Admin → Plugins → AI → Logs. Treat logs as sensitive: they can include submitted text and responses. Never paste credentials or private request contents into a support topic.

Additional resources