# Discourse AI - Embeddings
**URL:** https://meta.discourse.org/t/discourse-ai-embeddings/259603
**Category:** Site Management
**Tags:** ai, ai-search, related-topics
**Created:** [April 24, 2023, 7:40pm UTC](https://meta.discourse.org/t/discourse-ai-embeddings/259603 "2023-04-24T19:40:35Z")
**Posts on this page:** 20
**Page:** 1
### Author:  [@Discourse](https://meta.discourse.org/u/Discourse)
#### Post date: [April 24, 2023, 7:40pm UTC](https://meta.discourse.org/t/discourse-ai-embeddings/259603/1 "2023-04-24T19:40:35Z")
> š This topic covers the configuration of the Embeddings module of the [Discourse AI](https://meta.discourse.org/t/discourse-ai/259214?slient=true) plugin. It explains what embeddings are, how theyāre used, and how to set them up.
>
> š Required user level: Administrator
Embeddings are a crucial component of the Discourse AI plugin, enabling features like [Related topics](https://meta.discourse.org/t/discourse-ai-related-topics/281807) and [AI search](https://meta.discourse.org/t/discourse-ai-ai-search/282420). This guide will walk you through the setup and use of embeddings in your Discourse instance.
## What are Embeddings?
Embeddings are numerical representations of text that capture semantic meaning. In Discourse, theyāre used to:
1. Generate related topics at the bottom of topic pages
2. Enable semantic search functionality
## Setting up Embeddings
### For hosted customers
If youāre a hosted customer, embeddings are pre-configured. You can simply enable the AI features that depend on them.
### For self-hosted instances
If youāre self-hosting, refer to the [Discourse AI self-hosted guide](https://meta.discourse.org/t/discourse-ai-self-hosted-guide/259598/1) for detailed setup instructions.
## Configuring Embedding Definitions
Embedding models are now configured as **Embedding Definitions** in the admin UI. Navigate to `Admin` ā `AI` plugin ā `Embeddings` tab. When adding a new embedding definition, you can choose from pre-configured **presets** or configure one manually.
Available presets include:
- **text-embedding-3-large** (OpenAI)
- **text-embedding-3-small** (OpenAI)
- **text-embedding-ada-002** (OpenAI)
- **gemini-embedding-001** (Google)
- **bge-large-en** (Hugging Face)
- **bge-m3** (Hugging Face)
- **multilingual-e5-large** (Hugging Face)
Each embedding definition includes: display name, provider, URL, API key (or AI Secret), tokenizer, dimensions, distance function, max sequence length, and optional embed/search prompts.
## Configuring embeddings
Navigate to `Admin` ā `Plugins` ā `Discourse AI`, ensure the following settings are enabled.
1. **ai embeddings enabled** : Turn the embeddings module on or off
2. **ai embeddings selected model** : Select which embedding definition to use for generating embeddings
Optional settings that can be tweakedā¦
- **AI embeddings generate for pms** : Decide whether to generate embeddings for personal messages
- **AI embeddings semantic related topics enabled** : Enable or disable the āRelated topicsā feature
- **AI embeddings semantic related topics** : The maximum number of related topics to be shown
- **AI embeddings semantic related include closed topics** : Include closed topics in related topic results
- **AI embeddings semantic related age penalty** : Apply an exponential age penalty to topics in related results (0.0 disables, higher values penalize older topics more)
- **AI embeddings semantic related age time scale** : Time scale in days for age penalty calculation (default: 365)
- **AI embeddings semantic search enabled** : Enable full-page AI search
- **AI embeddings semantic quick search enabled** : Enable semantic search option in the search menu popup
- **AI embeddings semantic search use hyde** : Enable HyDE (Hypothetical Document Embedding) for semantic search
- **AI embeddings semantic search hyde agent** : The AI agent used to expand search terms when HyDE is enabled
## Providers
Discourse AI supports multiple embedding providers:
- OpenAI
- Google
- Hugging Face (for open source/open weights models)
- Cloudflare Workers AI
For hosted customers, Discourse provides pre-configured (seeded) embedding definitions that work out of the box.
## Features
### [Related Topics](https://meta.discourse.org/t/discourse-ai-related-topics/281807)
When enabled, a āRelated Topicsā section appears at the bottom of topic pages, linking to semantically similar discussions.
### [AI Search](https://meta.discourse.org/t/discourse-ai-ai-search/282420)
Embeddings power the semantic search option on the full-page search interface.
Semantic search can optionally use HyDE (Hypothetical Document Embedding). When enabled via `ai embeddings semantic search use hyde`, the search term is expanded using the AI agent configured in `ai embeddings semantic search hyde agent`. The expanded search is then converted to a vector and used to find similar topics. This technique adds some latency to search but can improve results.
When selecting an agent for HyDE, choose a fast model like Gemini Flash, Claude Haiku, GPT-4o Mini, or the latest available models.
## Generating embeddings
Embeddings are generated automatically for new posts. To generate embeddings for existing content:
1. Discourse will automatically backfill embeddings for older topics via a scheduled job that runs every 5 minutes
2. The backfill processes topics in order of recent activity first
## FAQs
**Q: How are related topics determined?**
A: Related topics are based solely on embeddings, which include the title, category, tags, and posts content
**Q: Can I exclude certain topics from related topics?**
A: Yes, thereās a site setting to remove closed topics from the results
**Q: Do embeddings work for historical posts?**
A: Yes, the system will automatically backfill embeddings for all your content
## Additional resources
- [Discourse AI](https://meta.discourse.org/t/discourse-ai/259214/?slient=true)
- [Discourse AI - Self-Hosted Guide](https://meta.discourse.org/t/discourse-ai-self-hosted-guide/259598/?slient=true)
> Last edited by @tobiaseigen 2025-09-25T15:06:15Z
>
> Last checked by @hugh 2024-08-06T04:16:01Z
>
> > **Check document**
> >
> > Perform check on document:
---
### Author:  [@kuaza](https://meta.discourse.org/u/kuaza)
#### Post date: [July 23, 2023, 10:36am UTC](https://meta.discourse.org/t/discourse-ai-embeddings/259603/5 "2023-07-23T10:36:40Z")
Great work, thanks first of all, but I canāt see similar topics under the topics, somehow, my settings are like this, I added an openai key. Semantic search works, but how can I show similar articles under topics?
---
### Author:  [@Falco](https://meta.discourse.org/u/Falco)
#### Post date: [July 27, 2023, 2:03pm UTC](https://meta.discourse.org/t/discourse-ai-embeddings/259603/6 "2023-07-27T14:03:46Z")
> [@kuaza](#):
>
> but how can I show similar articles under topics?
If you want to use OpenAI for embeddings you must set `ai embeddings model` to `text-embedding-ada-002`.
---
### Author:  [@bigfudge](https://meta.discourse.org/u/bigfudge)
#### Post date: [August 17, 2023, 9:01am UTC](https://meta.discourse.org/t/discourse-ai-embeddings/259603/7 "2023-08-17T09:01:25Z")
How are the jobs to generate embeddings scheduled? From the code it seems like embeddings are only generated when the page is viewed and embeddings are missing. Is there a way to generate embeddings for the whole site when turning the feature on?
---
### Author:  [@Falco](https://meta.discourse.org/u/Falco)
#### Post date: [August 17, 2023, 8:56pm UTC](https://meta.discourse.org/t/discourse-ai-embeddings/259603/8 "2023-08-17T20:56:03Z")
You can also run `rake ai:embeddings:backfill` to generate embeddings for all topics eagerly.
---
### Author:  [@EricGT](https://meta.discourse.org/u/EricGT)
#### Post date: [August 18, 2023, 6:56pm UTC](https://meta.discourse.org/t/discourse-ai-embeddings/259603/9 "2023-08-18T18:56:25Z")
Suggestion
Sometimes reading a topic one knows most of the noted background but there are also some mentions that are not known. While there is summarization for summarizing an entire topic up to that point what would also be of help would be an AI option that inserts a glossary for the topic as a post near the top and updates it if a user selects a word or phrase that it wants the AI to include in the glossary.
* * *
Today in reading this [topic](https://community.openai.com/t/interviewer-agent-rather-than-q-a-agent/320527) there was one reference I did not recognize so looked it up and added a reply with a reference for it. While I know the remaining references I am sure there are others, especially those new to LLMs and such, that would have no idea of many of the noted references and if the AI could help them they would visit the site much more often.
While I know what RAG means in this starting [post](https://community.openai.com/t/interviewer-agent-rather-than-q-a-agent/320527?u=ericgt), how many really know that?
> **What is RAG (Click triangle to expand)**
>
> [How do domain-specific chatbots work? An Overview of Retrieval Augmented Generation (RAG)](https://scriv.ai/guides/retrieval-augmented-generation-overview/?ref=emergentmind)
* * *
Note: Did not know with which topic to post this but since it needed embeddings to work posted it here. Please move this if it makes more sense elsewhere or as the Discourse AI plugin changes.
---
### Author:  [@swong](https://meta.discourse.org/u/swong)
#### Post date: [October 27, 2023, 10:16pm UTC](https://meta.discourse.org/t/discourse-ai-embeddings/259603/10 "2023-10-27T22:16:37Z")
Are embeddings the only variable when determining āRelated Topicsā? Or are there any other factors that are considered (e.g. author, topic score, topic age, category, etc)?
---
### Author:  [@Falco](https://meta.discourse.org/u/Falco)
#### Post date: [October 27, 2023, 10:47pm UTC](https://meta.discourse.org/t/discourse-ai-embeddings/259603/11 "2023-10-27T22:47:49Z")
Only the embeddings, but those contain the title, category, tags and posts. There is a site setting to remove closed topics from the results too.
---
### Author:  [@JammyDodger](https://meta.discourse.org/u/JammyDodger)
#### Post date: [December 14, 2023, 11:47am UTC](https://meta.discourse.org/t/discourse-ai-embeddings/259603/12 "2023-12-14T11:47:52Z")
7 posts were split to a new topic: [Is full page semantic search only in English?](https://meta.discourse.org/t/is-full-page-semantic-search-only-in-english/288665)
---
### Author:  [@Falco](https://meta.discourse.org/u/Falco)
#### Post date: [February 7, 2024, 5:20pm UTC](https://meta.discourse.org/t/discourse-ai-embeddings/259603/20 "2024-02-07T17:20:30Z")
2 posts were split to a new topic: [Differences in search latency between AI semantic and keyword search](https://meta.discourse.org/t/differences-in-search-latency-between-ai-semantic-and-keyword-search/294571)
---
### Author:  [@Isambard](https://meta.discourse.org/u/Isambard)
#### Post date: [March 23, 2024, 10:41pm UTC](https://meta.discourse.org/t/discourse-ai-embeddings/259603/21 "2024-03-23T22:41:50Z")
I wish I found this a few months ago. I already created embeddings using bge-small-en-v1.5 and hosted them in an external database.
I will see if it can be shoehorned into this āstandardā set-up!
---
### Author:  [@fokx](https://meta.discourse.org/u/fokx)
#### Post date: [April 29, 2024, 3:28am UTC](https://meta.discourse.org/t/discourse-ai-embeddings/259603/22 "2024-04-29T03:28:14Z")
> [@Falco](#):
>
> rake
I find a little bug in the recent version leading to `rake ai:embeddings:backfill` failed:
```plaintext
root@nbg-webxj:/var/www/discourse# rake ai:embeddings:backfill
rake aborted!
NameError: uninitialized constant Parallel (NameError)
Parallel.each(topics.all, in_processes: args[:concurrency].to_i, progress: "Topics") do |t|
^^^^^^^^
/var/www/discourse/plugins/discourse-ai/lib/tasks/modules/embeddings/database.rake:27:in `block in '
/usr/local/bin/bundle:25:in `load'
/usr/local/bin/bundle:25:in `'
Tasks: TOP => ai:embeddings:backfill
(See full trace by running task with --trace)
```
I suspect the culprit is that the `parallel` gem is neither installed in this plugin, nor in Discourse core(only find one in the `if ENV["IMPORT"] == "1"` block: ` gem "parallel", require: false`).
I find the `ruby-progressbar` gem also required to perform `rake ai:embeddings:backfill`.
I make a simple PR on Github:
[https://github.com/discourse/discourse-ai/pull/595](https://github.com/discourse/discourse-ai/pull/595)
---
### Author:  [@Hifihedgehog](https://meta.discourse.org/u/Hifihedgehog)
#### Post date: [May 16, 2024, 3:52pm UTC](https://meta.discourse.org/t/discourse-ai-embeddings/259603/23 "2024-05-16T15:52:02Z")
Note to others that this rake method seems to have been demoted/semi-deprecated since per Falco on GitHub:
> Thanks for the PR [@fokx](https://github.com/fokx), but Iāve left those out unintentionally as the rake task fell out out favor and should only be used in rare occasions by experienced operators who can easily install those out of band.
---
### Author:  [@Hifihedgehog](https://meta.discourse.org/u/Hifihedgehog)
#### Post date: [May 16, 2024, 4:05pm UTC](https://meta.discourse.org/t/discourse-ai-embeddings/259603/24 "2024-05-16T16:05:59Z")
> [@Falco](#):
>
> It also adds a Semantic Search option on the full page search:
Is the semantic search option no longer shown in that dropdown and instead comprehended or enabled through the AI toggle?
---
### Author:  [@PeakProsperity](https://meta.discourse.org/u/PeakProsperity)
#### Post date: [July 18, 2024, 1:58pm UTC](https://meta.discourse.org/t/discourse-ai-embeddings/259603/25 "2024-07-18T13:58:48Z")
Can you confirm for me if the embeddings will only work on posts _after installing_ or will it also allow us to semantic-search all _historical posts_? Iām hoping the latter! Thanks.
---
### Author:  [@Falco](https://meta.discourse.org/u/Falco)
#### Post date: [July 22, 2024, 2:18pm UTC](https://meta.discourse.org/t/discourse-ai-embeddings/259603/26 "2024-07-22T14:18:43Z")
Itās the later, as it will automatically backfill embeddings for all your content.
---
### Author:  [@packman](https://meta.discourse.org/u/packman)
#### Post date: [August 14, 2024, 10:41am UTC](https://meta.discourse.org/t/discourse-ai-embeddings/259603/27 "2024-08-14T10:41:32Z")
Iām trying to set up AI Embeddings using Gemini Flash but I canāt get it to work. I canāt find good descriptions/examples of all the settings fields though, so I might have missed one or two that are important. I donāt know if the āai\_embeddings\_modelā setting is required, but if I set it to āgeminiā I get the following errorā¦
Iāve not been able to find the ai\_gemini\_api\_key setting. I do have Gemini Flash set up as an LLM with an API key and thatās working elsewhere, e.g. summarization, but Iām assuming this is wanting the API key entered somewhere else?
---
### Author:  [@Overgrow](https://meta.discourse.org/u/Overgrow)
#### Post date: [September 10, 2024, 2:35pm UTC](https://meta.discourse.org/t/discourse-ai-embeddings/259603/29 "2024-09-10T14:35:58Z")
> [@Discourse](#):
>
> Self-hosters can use the rake task `ai:embeddings:backfill` to generate embeddings for all topics
I suppose this would work with OpenAI too, wouldnāt it?
It would be great if it could support their [Batch API](https://platform.openai.com/docs/guides/batch/overview) (50% discount)
---
### Author:  [@Falco](https://meta.discourse.org/u/Falco)
#### Post date: [September 10, 2024, 3:51pm UTC](https://meta.discourse.org/t/discourse-ai-embeddings/259603/30 "2024-09-10T15:51:22Z")
> [@Overgrow](#):
>
> I suppose this would work with OpenAI too, wouldnāt it?
Yes, but nowadays we backfill automatically in the background, so this isnāt mandatory.
> [@Overgrow](#):
>
> It would be great if it could support their [Batch API](https://platform.openai.com/docs/guides/batch/overview) (50% discount)
For price conscious peeps, we support great open weights model that you can run on your own hardware.
---
### Author:  [@Overgrow](https://meta.discourse.org/u/Overgrow)
#### Post date: [September 10, 2024, 6:45pm UTC](https://meta.discourse.org/t/discourse-ai-embeddings/259603/31 "2024-09-10T18:45:36Z")
Thanks. Do I understand it correctly that backfill is when the vectorization happens? When switching between models, do the vectors need to be recalculated (Are they āproprietaryā)? I assume yes.
Itād be useful to know how the costs of using the OpenAI API stack up against investing in a GPU-powered server with opensource solution. Is there a formula or any way to estimate the number of tokens used? Weāre only using the API to vectorize posts, not for calculating vector distances, right? So, the number of tokens used depends on how much content we have, correct?
I assume that for both related topics and AI-powered search, all posts need to be vectorized only once, so I can calculate the total number of words in posts table and derive the number of tokens needed. The same process would apply to the daily addition of posts. Iām neglecting the search phrases for now.
[Next page](https://meta.discourse.org/t/discourse-ai-embeddings/259603.md?page=2)