Skip to content

Professional services

Need expert help? RAGcon offers:

  • RAGflow Support
  • RAGflow Hosting
  • Moodle Support
Talk to RAGcon →

Set up RAGflow

This page connects Moodle to your RAGflow instance once, centrally. All suite plugins reuse this provider, so you only do this setup a single time.

What you need

  • A reachable RAGflow base URL (e.g. https://ragflow.example.org).
  • A RAGflow API key (RAGflow → API → generate a key).
  • At least one RAGflow assistant (chat) bound to a knowledge base / dataset that contains your documents. See Prepare a knowledge base below.

1. Prepare a knowledge base in RAGflow

In your RAGflow instance:

  1. Create a dataset and upload the documents you want answers to draw from.
  2. Wait until the documents are parsed/embedded (RAGflow shows the progress).
  3. Create an assistant (chat) and bind it to that dataset.
  4. Note the assistant so you can select it in Moodle.

Check the assistant's system prompt

RAGflow's default assistant prompt tells the model to "list the knowledge-base entries", which makes it wrongly answer "the knowledge base is empty" when a question has no matches (even though the dataset has content). If you create the assistant manually, replace its system prompt with a cleaner one — see Answer wording when nothing is found in the admin guide. (Assistants the Tutor block creates already get a clean prompt.)

Embedding model & context window

Retrieval embeds your query with the dataset's embedding model. Very long queries can exceed a small model's context window. The suite already keeps queries short, but choose an embedding model appropriate to your content.

2. Add the RAGflow AI provider in Moodle

  1. Go to Site administration → General → AI → AI providers (Moodle's AI subsystem).
  2. Add a new RAGflow provider instance.
  3. Enter the base URL and API key from your RAGflow instance.
  4. Configure the actions you want (chat, and optionally source display / memory) and select the assistant to use.
  5. Enable the provider and save.

Verify the connection

If the base URL or key is wrong, or RAGflow is unreachable, chats fail with "Unexpected response from RAGflow". Administrators (and users with aiprovider/ragflow:viewerrordetails) see the technical cause under a Details disclosure — e.g. HTTP 502 (RAGflow down) or an embedding error. Use that to diagnose the connection.

3. Enable the plugins you want

Each surface is enabled independently:

  • Tutor block — add the RAGflow Tutor block to a course; teachers upload course documents into the block's own knowledge base.
  • Search block — add the RAGflow Search block to a course or dashboard.
  • Helpdesk placement — enable the placement under AI → AI placements; a help drawer appears site-wide.
  • Usage dashboard — view under Site administration → Reports → RAGflow Dashboard.

4. Permissions

  • aiprovider/ragflow:viewerrordetails — who may see the technical error cause on a failed chat (default: Manager + Teacher; site admins always). Keep it off for ordinary users, since the cause can reveal server-side internals.
  • Each surface has its own :use capability (e.g. block/ragflowtutor:use, aiplacement/ragflowhelpdesk:use) and management capabilities for editing knowledge bases.

Troubleshooting

Symptom Likely cause What to check
Unexpected response from RAGflow + HTTP 502/504 RAGflow unreachable / down Is the RAGflow service up? Base URL correct and reachable from the Moodle server?
Unexpected response + HTTP 401/403 Bad API key Regenerate the key in RAGflow, update the provider instance
Embedding / context-window error Query too long for the embedding model Use a larger-context embedding model, or shorter documents/queries
No answers, empty sources Dataset not parsed yet, or assistant not bound to the dataset Confirm parsing finished; confirm the assistant is bound to the dataset

Administrators can also open Reports → RAGflow Dashboard and enable a component's debug capture to see the exact request/response of recent calls.

Note: This documentation was created with the help of AI. Spotted an error, an omission, or something unclear? Please report it in the ragcon-docs GitHub repository so we can fix it.