diff --git a/docs/.vitepress/en.ts b/docs/.vitepress/en.ts index 1f250fefe..e19b53e49 100644 --- a/docs/.vitepress/en.ts +++ b/docs/.vitepress/en.ts @@ -491,6 +491,10 @@ const side = { text: "Redroid", link: "/use-cases/host-cloud-android", }, + { + text: "DeerFlow", + link: "/use-cases/deerflow", + }, ], }, ], diff --git a/docs/public/images/manual/use-cases/deerflow-add-mcp-server.png b/docs/public/images/manual/use-cases/deerflow-add-mcp-server.png new file mode 100644 index 000000000..7505e8491 Binary files /dev/null and b/docs/public/images/manual/use-cases/deerflow-add-mcp-server.png differ diff --git a/docs/public/images/manual/use-cases/deerflow-app-volume.png b/docs/public/images/manual/use-cases/deerflow-app-volume.png new file mode 100644 index 000000000..b8ca7c694 Binary files /dev/null and b/docs/public/images/manual/use-cases/deerflow-app-volume.png differ diff --git a/docs/public/images/manual/use-cases/deerflow-ask-ai-to-edit.png b/docs/public/images/manual/use-cases/deerflow-ask-ai-to-edit.png new file mode 100644 index 000000000..179b3b9ab Binary files /dev/null and b/docs/public/images/manual/use-cases/deerflow-ask-ai-to-edit.png differ diff --git a/docs/public/images/manual/use-cases/deerflow-conf-yaml-in-files.png b/docs/public/images/manual/use-cases/deerflow-conf-yaml-in-files.png new file mode 100644 index 000000000..0ff009d16 Binary files /dev/null and b/docs/public/images/manual/use-cases/deerflow-conf-yaml-in-files.png differ diff --git a/docs/public/images/manual/use-cases/deerflow-configmap.png b/docs/public/images/manual/use-cases/deerflow-configmap.png new file mode 100644 index 000000000..4599bcea1 Binary files /dev/null and b/docs/public/images/manual/use-cases/deerflow-configmap.png differ diff --git a/docs/public/images/manual/use-cases/deerflow-configure-tavily.png b/docs/public/images/manual/use-cases/deerflow-configure-tavily.png new file mode 100644 index 000000000..f5b5661bf Binary files /dev/null and b/docs/public/images/manual/use-cases/deerflow-configure-tavily.png differ diff --git a/docs/public/images/manual/use-cases/deerflow-enter-prompt.png b/docs/public/images/manual/use-cases/deerflow-enter-prompt.png new file mode 100644 index 000000000..f1f417eef Binary files /dev/null and b/docs/public/images/manual/use-cases/deerflow-enter-prompt.png differ diff --git a/docs/public/images/manual/use-cases/deerflow-generate-research-plan.png b/docs/public/images/manual/use-cases/deerflow-generate-research-plan.png new file mode 100644 index 000000000..fe784aa0b Binary files /dev/null and b/docs/public/images/manual/use-cases/deerflow-generate-research-plan.png differ diff --git a/docs/public/images/manual/use-cases/deerflow-generate-research-report.png b/docs/public/images/manual/use-cases/deerflow-generate-research-report.png new file mode 100644 index 000000000..2a8e28c67 Binary files /dev/null and b/docs/public/images/manual/use-cases/deerflow-generate-research-report.png differ diff --git a/docs/public/images/manual/use-cases/deerflow-locate-containers.png b/docs/public/images/manual/use-cases/deerflow-locate-containers.png new file mode 100644 index 000000000..fd72a6546 Binary files /dev/null and b/docs/public/images/manual/use-cases/deerflow-locate-containers.png differ diff --git a/docs/public/images/manual/use-cases/deerflow-restart.png b/docs/public/images/manual/use-cases/deerflow-restart.png new file mode 100644 index 000000000..4b588b43b Binary files /dev/null and b/docs/public/images/manual/use-cases/deerflow-restart.png differ diff --git a/docs/public/images/manual/use-cases/deerflow-review-research-activities.png b/docs/public/images/manual/use-cases/deerflow-review-research-activities.png new file mode 100644 index 000000000..b314df8b8 Binary files /dev/null and b/docs/public/images/manual/use-cases/deerflow-review-research-activities.png differ diff --git a/docs/public/images/manual/use-cases/deerflow.png b/docs/public/images/manual/use-cases/deerflow.png new file mode 100644 index 000000000..bda6b25ba Binary files /dev/null and b/docs/public/images/manual/use-cases/deerflow.png differ diff --git a/docs/public/images/manual/use-cases/ollama-authentication-level.png b/docs/public/images/manual/use-cases/ollama-authentication-level.png new file mode 100644 index 000000000..b91f00923 Binary files /dev/null and b/docs/public/images/manual/use-cases/ollama-authentication-level.png differ diff --git a/docs/public/images/manual/use-cases/ollama-endpoint.png b/docs/public/images/manual/use-cases/ollama-endpoint.png new file mode 100644 index 000000000..ebb7eb67d Binary files /dev/null and b/docs/public/images/manual/use-cases/ollama-endpoint.png differ diff --git a/docs/public/images/manual/use-cases/ollama.png b/docs/public/images/manual/use-cases/ollama.png index b1e7b138c..c4c7a3d08 100644 Binary files a/docs/public/images/manual/use-cases/ollama.png and b/docs/public/images/manual/use-cases/ollama.png differ diff --git a/docs/use-cases/deerflow.md b/docs/use-cases/deerflow.md new file mode 100644 index 000000000..230ea6bf6 --- /dev/null +++ b/docs/use-cases/deerflow.md @@ -0,0 +1,199 @@ +--- +outline: [2, 3] +description: Learn how to set up DeerFlow on your Olares device, complete with Ollama integration and Tavily for web research. +--- + +# Build a local deep research agent with DeerFlow +DeerFlow is an open-source framework that transforms a simple research topic into a comprehensive, detailed report. + +This guide will walk through the process of setting up DeerFlow on your Olares device, integrating it with a local Ollama model and the Tavily search engine for web-enabled research. + +## Learning objectives +In this guide, you will learn how to: +- Configure DeerFlow to communicate with a local LLM via Ollama. +- Configure the Tavily search API for web access. +- Execute deep research tasks and manage reports. + +## Prerequisites +Before you begin, make sure: +- Ollama is installed and running in your Olares environment. +- At least one model installed using Ollama. See [Ollama](./ollama.md) for details. +- You have a [Tavily](https://www.tavily.com/) account (a free account is sufficient). + +## Install DeerFlow +1. Open **Market**, and search for "DeerFlow". + ![Install DeerFlow](/images/manual/use-cases/deerflow.png#bordered) + +2. Click **Get**, then **Install**, and wait for installation to complete. + +## Configure DeerFlow +DeerFlow requires connection details for the LLM. You will configure this by editing the `conf.yaml` file using either the graphical interface or the command line. + +### Configure DeerFlow to use Ollama + + + + + + + +### Configure DeerFlow to use Tavily +To enable web search, add your Tavily API key to the application configuration. +1. In Control Hub, select the DeerFlow project. +2. Click **Configmaps** in the resource list and select **deerflow-config**. + ![Browse to DeerFlow's configmaps](/images/manual/use-cases/deerflow-configmap.png#bordered) + +3. Click edit_square in the top-right to open the editor. +4. Add the following key-value pairs under the `data` section: + ```yaml + SEARCH_API: tavily + TAVILY_API_KEY: tvly-xxx # Your Tavily API Key + ``` + ![Configure Tavily](/images/manual/use-cases/deerflow-configure-tavily.png#bordered) + +5. Click **Confirm** to save the changes. + +### Restart DeerFlow +Restart the service to apply the new model and search configurations. + +1. In Control Hub, select the DeerFlow project. +2. Under **Deployments**, locate **deerflow** and click **Restart**. + ![Restart DeerFlow](/images/manual/use-cases/deerflow-restart.png#bordered) + +2. In the confirmation dialog, type `deerflow` and click **Confirm**. +3. Wait for the status icon to turn green, which indicates the service has successfully restarted. + +## Run DeerFlow +### Run a deep research task +1. Open **DeerFlow** from the Olares Launchpad. +2. Click **Get Started** and enter your research topic in the prompt box. + ![Enter research prompt](/images/manual/use-cases/deerflow-enter-prompt.png#bordered) + +3. Click the wand icon to have DeerFlow refine your prompt for better results. +4. Enable **Investigation**. +5. Select your preferred writing style (e.g., **Popular Science**). +6. Click arrow_upward to send the request. + +DeerFlow will generate a preliminary research plan. Review and edit this plan if necessary, or allow it to proceed. +![Generate research plan](/images/manual/use-cases/deerflow-generate-research-plan.png#bordered) + +Once the process is complete, a detailed analysis report will be displayed. +![View research report](/images/manual/use-cases/deerflow-generate-research-report.png#bordered) + +To audit the sources and steps taken, click the **Activities** tab. +![Review research activities](/images/manual/use-cases/deerflow-review-research-activities.png#bordered) +### Edit and save the report +:::info Verify citations +AI models may occasionally generate inaccurate citations or "hallucinated" links. Manually verify important sources in the citations section. +::: + +1. Click edit in the top-right corner to enter editing mode. +2. You can adjust formatting using Markdown or select a section and ask the AI to improve or expand on it. + ![Ask AI to edit the report](/images/manual/use-cases/deerflow-ask-ai-to-edit.png#bordered) +3. Click undo in the top-right corner to exit editing mode. +4. Click download to save the report to your local machine as a Markdown file. + +## Add an MCP server +The Model Context Protocol (MCP) extends DeerFlow's capabilities by integrating external tools. For example, adding the Fetch server allows the agent to scrape and convert web content into Markdown for analysis. + +1. Open your DeerFlow app, and click settings to open the **Settings** dialog. +2. Select the **MCP** tab and click **Add Servers**. +3. Paste the JSON configuration for the server. The following example adds the fetch server: + ```json + { + "mcpServers": { + "fetch": { + "command": "uvx", + "args": ["mcp-server-fetch"] + } + } + } + ``` +4. Click **Add**. The server is automatically enabled and available for research agents. + ![Add MCP server](/images/manual/use-cases/deerflow-add-mcp-server.png#bordered) + +## Turn research report to a podcast (TTS) +DeerFlow can convert reports into MP3 audio using a Text-to-Speech (TTS) service, such as Volcengine TTS. This requires adding API credentials to the application environment. + +1. Obtain your **Access Token** and **App ID** from the [Volcengine](https://console.volcengine.com) console. +2. In Control Hub, select the DeerFlow project and go to **Configmaps** > **deerflow-config**. +3. Click the **Edit** icon in the top-right corner. +4. Add the following keys under the `data` section: + ```yaml + VOLCENGINE_TTS_ACCESS_TOKEN: # Your Access Token + VOLCENGINE_TTS_APPID: # Your App ID + ``` +5. Click **Confirm** to save the changes. +6. Navigate to **Deployments** > **deerflow** and click **Restart**. + +Once restarted, DeerFlow should detect these keys and the podcast/TTS feature will be available. + +## FAQ +### DeerFlow does not generate a response +If the agent fails to start or hangs: +- **Check model compatibility:** DeerFlow does not support reasoning models (e.g., DeepSeek R1). Switch to a standard chat model and try again. +- **Check endpoint configuration:** Ensure the Ollama API endpoint in `conf.yaml` includes the `/v1` suffix. + +### No web search results during the research +If the report is generic and lacks external data: +- **Check model capabilities:** The selected LLM may lack strong tool-calling capabilities. Switch to a model known for effective tool use, such as Qwen 2.5 or Llama 3.1. +- **Verify API Key:** Ensure the `TAVILY_API_KEY` in the ConfigMap is correct and the account has remaining quota. \ No newline at end of file diff --git a/docs/use-cases/index.md b/docs/use-cases/index.md index a1f60305f..232dc2caf 100644 --- a/docs/use-cases/index.md +++ b/docs/use-cases/index.md @@ -17,5 +17,6 @@ From running AI models to building seamless workflows across your self-hosted se { title: 'Jellyfin', link: './stream-media.html', tags: ['Entertainment']}, { title: 'Steam', link: './stream-game.html', tags: ['Entertainment']}, { title: 'Redroid', link: './host-cloud-android.html', tags: ['Virtual Machine']}, + { title: 'DeerFlow', link: './host-cloud-android.html', tags: ['AI']}, ]" /> \ No newline at end of file diff --git a/docs/use-cases/ollama.md b/docs/use-cases/ollama.md index 594b5ca5a..fa2e85e6e 100644 --- a/docs/use-cases/ollama.md +++ b/docs/use-cases/ollama.md @@ -1,29 +1,26 @@ --- outline: [2, 3] -description: Learn how to download and manage AI models locally using Ollama CLI within the Olares environment. +description: Learn how to install Ollama on Olares, manage models using the CLI, and configure it as a central AI service for other applications. --- -# Download and run AI models locally via Ollama -Ollama is a lightweight platform that allows you to run open-source AI models like `deepseek-r1` and `gemma3` directly on your machine. Within Olares, you can integrate Ollama with graphical interfaces like Open WebUI to add more features and simplify interactions. - -This guide will show you how to set up and use Ollama CLI on Olares. +# Download and run local AI models via Ollama +Ollama is a lightweight platform that allows you to run open-source AI models like `gemma3` and `deepseek-r1` directly on your machine. Within Olares, you can integrate Ollama with graphical interfaces like Open WebUI or other agents to add more features and simplify interactions. +## Learning objectives +In this guide, you will learn how to: +- Use the Ollama CLI on Olares to manage local LLMs. +- Configure Ollama as an API service for internal and external apps. ## Before you begin -Before you start, ensure that: -- You have Olares admin privileges. -- Install LarePass and [enable LarePass VPN](../manual/larepass/private-network.md#enable-vpn-on-larepass) on your device. +Before you start, ensure that you have Olares admin privileges. ## Install Ollama +1. Open **Market**, and search for "Ollama". +2. Click **Get**, then **Install**, and wait for installation to complete. + ![Install Ollama](/images/manual/use-cases/ollama.png#bordered) -Directly install Ollama from the Market. - -Once installation is complete, you can access Ollama terminal from the Launchpad. - -![Ollama](/images/manual/use-cases/ollama.png#bordered) -## Ollama CLI -Ollama CLI allows you to manage and interact with AI models directly. Below are the key commands and their usage: - -### Download model +## Manage models with the Ollama CLI +Ollama CLI allows you to manage and interact with AI models directly from the Olares terminal. Below are the key commands. +### Download a model :::tip Check Ollama library If you are unsure which model to download, check the [Ollama Library](https://ollama.com/library) to explore available models. ::: @@ -32,7 +29,7 @@ To download a model, use the following command: ollama pull [model] ``` -### Run model +### Run a model :::tip If the specified model has not been downloaded yet, the `ollama run` command will automatically download it before running. ::: @@ -57,7 +54,7 @@ ollama stop [model] ``` ### List models -To view all models installed on your system, use: +To view all models you have downloaded, use: ```bash ollama list ``` @@ -78,6 +75,35 @@ To see all currently running models, use: ```bash ollama ps ``` +## Configure Ollama API Access +To use Ollama as the backend for other applications (such as DeerFlow inside Olares, or Obsidian on your laptop), you must configure the API to allow access from the local network. + +### Verify authentication level +By default, the API's authentication level is set to **Internal**, allowing applications on the same local network to access the API without a login check. +1. Open Settings, then navigate to **Applications** > **Ollama** > **Ollama API**. +2. Confirm that **Authentication level** is set to **Internal**. +3. Click **Submit** if you made changes. + ![Verify authentication level](/images/manual/use-cases/ollama-authentication-level.png#bordered) + +### Get the endpoint +1. On the same settings page, click **Set up endpoint**. +2. Copy the frontend address displayed in the dialog. Use this address as the Base URL or Host in your application's settings. + ![Get Ollama endpoint](/images/manual/use-cases/ollama-endpoint.png#bordered) + +:::tip For OpenAI-compatible endpoint +Some apps expect an OpenAI-compatible API. If the standard endpoint fails, try appending `/v1` to your address. For example: +``` +https://39975b9a1.{YOURUSERNAME}.olares.com/v1 +``` +::: +If the application forces you to enter an API Key, you can usually enter any string (e.g., `ollama`). + +### Ensure network connectivity +Because you set the authentication to "Internal", your application must be on the same local network as Olares to connect. +* **Local Network**: If your device (or the app running on Olares) is on the same Wi-Fi or LAN, you can connect directly using the frontend address. +* **Remote Access**: If you are accessing Olares remotely, you must enable [LarePass VPN](../manual/larepass/private-network.md#enable-vpn-on-larepass) on your client device. This creates a secure tunnel that treats your device as if it were on the local network. + ## Learn more -- [Learn how to run Ollama models with Open WebUI](openwebui.md) \ No newline at end of file +- [Run Ollama models with Open WebUI](./openwebui.md) +- [Integrate Ollama with DeerFlow](./deerflow.md) \ No newline at end of file