From cba2a9cd52ff6c5c1b4358f64730581fc81dfd52 Mon Sep 17 00:00:00 2001 From: Anna Rahn Date: Tue, 6 Oct 2026 12:28:15 -0700 Subject: [PATCH 1/8] documentation re-structuring --- docs/README.md | 19 +- docs/api/introduction.mdx | 23 +- docs/cloud.mdx | 293 ++--------------- docs/cloud/api.mdx | 97 ++++++ docs/cloud/faq.mdx | 63 ++++ docs/cloud/model-lifecycle.mdx | 59 ++++ docs/cloud/models.mdx | 94 ++++++ docs/docs.json | 68 +++- docs/faq.mdx | 48 +-- docs/index.mdx | 37 ++- docs/local.mdx | 57 ++++ docs/quickstart.mdx | 30 +- docs/sample-projects/research-brief-agent.mdx | 306 ++++++++++++++++++ 13 files changed, 840 insertions(+), 354 deletions(-) create mode 100644 docs/cloud/api.mdx create mode 100644 docs/cloud/faq.mdx create mode 100644 docs/cloud/model-lifecycle.mdx create mode 100644 docs/cloud/models.mdx create mode 100644 docs/local.mdx create mode 100644 docs/sample-projects/research-brief-agent.mdx diff --git a/docs/README.md b/docs/README.md index f3817d3c1..f11addb3f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,13 +1,19 @@ # Documentation -### Getting Started +### Getting started + * [Quickstart](https://docs.ollama.com/quickstart) +* [Ollama Cloud](https://docs.ollama.com/cloud) +* [Run Ollama locally](https://docs.ollama.com/local) * [Examples](./examples.md) + +### Local + +* [macOS](https://docs.ollama.com/macos) +* [Linux](https://docs.ollama.com/linux) +* [Windows](https://docs.ollama.com/windows) +* [Docker](https://docs.ollama.com/docker) * [Importing models](https://docs.ollama.com/import) -* [MacOS Documentation](https://docs.ollama.com/macos) -* [Linux Documentation](https://docs.ollama.com/linux) -* [Windows Documentation](https://docs.ollama.com/windows) -* [Docker Documentation](https://docs.ollama.com/docker) ### Reference @@ -19,5 +25,6 @@ ### Resources * [Troubleshooting Guide](https://docs.ollama.com/troubleshooting) -* [FAQ](https://docs.ollama.com/faq) +* [Local FAQ](https://docs.ollama.com/faq) +* [Cloud FAQ](https://docs.ollama.com/cloud/faq) * [Development guide](./development.md) diff --git a/docs/api/introduction.mdx b/docs/api/introduction.mdx index c72da657c..2d31af4cb 100644 --- a/docs/api/introduction.mdx +++ b/docs/api/introduction.mdx @@ -1,30 +1,43 @@ --- title: Introduction +description: Use the Ollama API locally or through Ollama Cloud with a shared request format. --- Use Ollama's API to run and interact with models. ## Get started -Follow the [quickstart](/quickstart) to install Ollama and make your first request. +Choose how the request reaches the model: -## Base URL +| Access path | Model runs on | Base URL | Authentication and model name | +| --- | --- | --- | --- | +| [Local model](/local) | Your hardware | `http://localhost:11434/api` | None by default; use the local model name | +| [Cloud model through Ollama](/cloud/models) | Ollama Cloud | `http://localhost:11434/api` | Run `ollama signin`; use a model name ending in `:cloud` | +| [Direct Cloud API](/cloud/api) | Ollama Cloud | `https://ollama.com/api` | Send an Ollama API key; use the Cloud API model name | -After installation, Ollama's API is served by default at: +Request bodies have the same shape for shared endpoints. The host, authentication, and model name depend on the access path. + +## Local API + +After you [install Ollama](/local), its API is served by default at: ``` http://localhost:11434/api ``` -For running cloud models on [ollama.com](https://ollama.com), the same API is available with the following base URL: +## Cloud API + +For direct access to models hosted on Ollama Cloud, use: ``` https://ollama.com/api ``` +Cloud API requests require an API key. See [Cloud API authentication](/cloud/api#authentication). + ## Example request -Once Ollama is running, its API is automatically available and can be accessed via `curl`: +Once Ollama is running locally, its API is automatically available and can be accessed with `curl`: ```shell curl http://localhost:11434/api/generate -d '{ diff --git a/docs/cloud.mdx b/docs/cloud.mdx index 2bc46471f..6f34bd658 100644 --- a/docs/cloud.mdx +++ b/docs/cloud.mdx @@ -1,292 +1,39 @@ --- -title: Cloud -sidebarTitle: Cloud +title: Ollama Cloud +sidebarTitle: Overview +description: Choose how to run Ollama Cloud models through the Ollama CLI, a local API, or the direct Cloud API. --- -## Cloud Models +Ollama Cloud runs larger models without requiring a powerful GPU. Cloud models support the same capabilities as local models, but inference runs on Ollama's cloud service. -Ollama's cloud models are a new kind of model in Ollama that can run without a powerful GPU. Instead, cloud models are automatically offloaded to Ollama's cloud service while offering the same capabilities as local models, making it possible to keep using your local tools while running larger models that wouldn't fit on a personal computer. +## Choose how to connect -### Supported models + + + Use the Ollama CLI, Python or JavaScript library, or your local Ollama API. Cloud model names use the `:cloud` suffix. + -For a list of supported models, see Ollama's [model library](https://ollama.com/search?c=cloud). + + Send authenticated requests to `https://ollama.com/api` without installing Ollama. + + -### Running Cloud models +Both options require an Ollama account. Browse the available models in the [cloud model library](https://ollama.com/search?c=cloud). -Ollama's cloud models require an account on [ollama.com](https://ollama.com). To sign in or create an account, run: +## Cloud models -``` -ollama signin -``` - - - - -To run a cloud model, open the terminal and run: - -``` -ollama run gpt-oss:120b-cloud -``` - - - - -First, pull a cloud model so it can be accessed: - -``` -ollama pull gpt-oss:120b-cloud -``` - -Next, install [Ollama's Python library](https://github.com/ollama/ollama-python): - -``` -pip install ollama -``` - -Next, create and run a simple Python script: - -```python -from ollama import Client - -client = Client() - -messages = [ - { - 'role': 'user', - 'content': 'Why is the sky blue?', - }, -] - -for part in client.chat('gpt-oss:120b-cloud', messages=messages, stream=True): - print(part['message']['content'], end='', flush=True) -``` - - - - -First, pull a cloud model so it can be accessed: - -``` -ollama pull gpt-oss:120b-cloud -``` - -Next, install [Ollama's JavaScript library](https://github.com/ollama/ollama-js): - -``` -npm i ollama -``` - -Then use the library to run a cloud model: - -```typescript -import { Ollama } from "ollama"; - -const ollama = new Ollama(); - -const response = await ollama.chat({ - model: "gpt-oss:120b-cloud", - messages: [{ role: "user", content: "Explain quantum computing" }], - stream: true, -}); - -for await (const part of response) { - process.stdout.write(part.message.content); -} -``` - - - - -First, pull a cloud model so it can be accessed: - -``` -ollama pull gpt-oss:120b-cloud -``` - -Run the following cURL command to run the command via Ollama's API: - -``` -curl http://localhost:11434/api/chat -d '{ - "model": "gpt-oss:120b-cloud", - "messages": [{ - "role": "user", - "content": "Why is the sky blue?" - }], - "stream": false -}' -``` - - - +Follow [Use Cloud models from Ollama](/cloud/models) to run a `:cloud` model from the CLI, official libraries, or the local Ollama API. ## Cloud API access -Cloud models can also be accessed directly on ollama.com's API. In this mode, ollama.com acts as a remote Ollama host. - -### Authentication - -For direct access to ollama.com's API, first create an [API key](https://ollama.com/settings/keys). - -Then, set the `OLLAMA_API_KEY` environment variable to your API key. - -``` -export OLLAMA_API_KEY=your_api_key -``` - -### Listing models - -For models available directly via Ollama's API, models can be listed via: - -``` -curl https://ollama.com/api/tags -``` - -### Generating a response - - - - -First, install [Ollama's Python library](https://github.com/ollama/ollama-python) - -``` -pip install ollama -``` - -Then make a request - -```python -import os -from ollama import Client - -client = Client( - host="https://ollama.com", - headers={'Authorization': 'Bearer ' + os.environ.get('OLLAMA_API_KEY')} -) - -messages = [ - { - 'role': 'user', - 'content': 'Why is the sky blue?', - }, -] - -for part in client.chat('gpt-oss:120b', messages=messages, stream=True): - print(part['message']['content'], end='', flush=True) -``` - - - - -First, install [Ollama's JavaScript library](https://github.com/ollama/ollama-js): - -``` -npm i ollama -``` - -Next, make a request to the model: - -```typescript -import { Ollama } from "ollama"; - -const ollama = new Ollama({ - host: "https://ollama.com", - headers: { - Authorization: "Bearer " + process.env.OLLAMA_API_KEY, - }, -}); - -const response = await ollama.chat({ - model: "gpt-oss:120b", - messages: [{ role: "user", content: "Explain quantum computing" }], - stream: true, -}); - -for await (const part of response) { - process.stdout.write(part.message.content); -} -``` - - - - -Generate a response via Ollama's chat API: - -``` -curl https://ollama.com/api/chat \ - -H "Authorization: Bearer $OLLAMA_API_KEY" \ - -d '{ - "model": "gpt-oss:120b", - "messages": [{ - "role": "user", - "content": "Why is the sky blue?" - }], - "stream": false - }' -``` - - - +Follow the [Cloud API guide](/cloud/api) to call `https://ollama.com/api` directly with an API key. ## Local only -Ollama can run in local-only mode by [disabling Ollama's cloud](./faq#how-do-i-disable-ollama-cloud-features) features. +Use [Local](/local) when you want inference to run on hardware you control. Ollama can also run in [local-only mode](/faq#how-do-i-disable-ollama-cloud-features) with Cloud features disabled. ## Retirements -Ollama will occasionally deprecate and retire older cloud models as newer and better open-source models are released. -Tools and applications relying on Ollama Cloud models may need to be updated to keep working. Impacted users will be -notified in advance of model deprecation and retirement. Deprecations will be communicated through email and on the -Ollama website. +Cloud models may be deprecated as newer models become available. See [Cloud model lifecycle](/cloud/model-lifecycle) for upcoming and past retirements. -Ollama Cloud model retirement does not affect local models. - -### Upcoming retirements - -| Retirement date | Model | Recommended alternative | -| --- | --- | --- | -| July 31, 2026 | `minimax-m2.5` | `minimax-m2.7` | -| July 31, 2026 | `kimi-k2.5` | `kimi-k2.6` | - -### Past retirements - - - - | Model | Recommended alternative | - | --- | --- | - | `deepseek-v3.1:671b` | `deepseek-v4-flash` | - | `deepseek-v3.2` | `deepseek-v4-flash` | - | `devstral-2:123b` | `mistral-large-3:675b` | - | `devstral-small-2:24b` | | - | `ministral-3:14b` | | - | `ministral-3:3b` | | - | `ministral-3:8b` | | - | `gemini-3-flash-preview` | `minimax-m3` | - | `gemma3:12b` | `gemma4:31b` | - | `gemma3:27b` | `gemma4:31b` | - | `gemma3:4b` | `gemma4:31b` | - | `glm-4.7` | `glm-5.2` | - | `glm-5` | `glm-5.2` | - | `minimax-m2.1` | `minimax-m3` | - | `qwen3-coder-next` | `qwen3.5:397b` | - | `qwen3-coder:480b` | `qwen3.5:397b` | - - - - | Model | Recommended alternative | - | --- | --- | - | `rnj-1:8b` | | - - - - | Model | Recommended alternative | - | --- | --- | - | `kimi-k2-thinking` | `kimi-k2.6` | - | `kimi-k2:1t` | `kimi-k2.6` | - | `minimax-m2` | `minimax-m3` | - | `glm-4.6` | `glm-5.1` | - | `qwen3-next:80b` | `qwen3.5` | - | `qwen3-vl:235b` | `qwen3.5` | - | `qwen3-vl:235b-instruct` | `qwen3.5` | - | `cogito-2.1:671b` | `deepseek-v4-flash` | - - +For questions about Cloud accounts, privacy, authentication, and requests, see the [Cloud FAQ](/cloud/faq). diff --git a/docs/cloud/api.mdx b/docs/cloud/api.mdx new file mode 100644 index 000000000..055434ab9 --- /dev/null +++ b/docs/cloud/api.mdx @@ -0,0 +1,97 @@ +--- +title: Cloud API +description: Authenticate and call the Ollama Cloud API directly at https://ollama.com/api. +--- + +Call Cloud models directly through `https://ollama.com/api`. In this mode, `ollama.com` is the Ollama host and a local Ollama installation is not required. + +## Authentication + +Create an [API key](https://ollama.com/settings/keys), then set it as an environment variable: + +```shell +export OLLAMA_API_KEY=your_api_key +``` + +Send the key as a bearer token in the `Authorization` header with every request. + +## List models + +```shell +curl https://ollama.com/api/tags \ + -H "Authorization: Bearer $OLLAMA_API_KEY" +``` + +## Generate a response + + + + +```shell +curl https://ollama.com/api/chat \ + -H "Authorization: Bearer $OLLAMA_API_KEY" \ + -d '{ + "model": "gpt-oss:120b", + "messages": [{"role": "user", "content": "Why is the sky blue?"}], + "stream": false + }' +``` + + + + +Install the [Ollama Python library](https://github.com/ollama/ollama-python): + +```shell +pip install ollama +``` + +```python +import os +from ollama import Client + +client = Client( + host="https://ollama.com", + headers={"Authorization": "Bearer " + os.environ["OLLAMA_API_KEY"]}, +) + +messages = [{"role": "user", "content": "Why is the sky blue?"}] + +for part in client.chat("gpt-oss:120b", messages=messages, stream=True): + print(part["message"]["content"], end="", flush=True) +``` + + + + +Install the [Ollama JavaScript library](https://github.com/ollama/ollama-js): + +```shell +npm i ollama +``` + +```typescript +import { Ollama } from "ollama"; + +const ollama = new Ollama({ + host: "https://ollama.com", + headers: { + Authorization: "Bearer " + process.env.OLLAMA_API_KEY, + }, +}); + +const response = await ollama.chat({ + model: "gpt-oss:120b", + messages: [{ role: "user", content: "Explain quantum computing" }], + stream: true, +}); + +for await (const part of response) { + process.stdout.write(part.message.content); +} +``` + + + + +For endpoint schemas and response fields, use the [API Reference](/api/introduction). diff --git a/docs/cloud/faq.mdx b/docs/cloud/faq.mdx new file mode 100644 index 000000000..e5b2a1a61 --- /dev/null +++ b/docs/cloud/faq.mdx @@ -0,0 +1,63 @@ +--- +title: Cloud FAQ +sidebarTitle: FAQ +description: Frequently asked questions about Ollama Cloud accounts, authentication, privacy, and requests. +--- + +For questions about installation, hardware, and the local Ollama server, see the [Local FAQ](/faq). + +## Does Ollama send my prompts and answers back to ollama.com? + +Ollama runs locally. We don't see your prompts or data when you run local models. + +When you use Cloud models, Ollama processes your prompts and responses to provide the service but does not store or log that content and never trains on it. Ollama collects basic account information and limited usage metadata that does not include prompt or response content. Ollama does not sell your data, and you can delete your account at any time. + +To prevent a local Ollama installation from using Cloud models and web search, enable [local-only mode](/faq#how-do-i-disable-ollama-cloud-features). + +## How do I manage the maximum number of requests the Ollama server can queue? + +When you access Cloud models through a local Ollama server, requests can queue locally while the server is busy. If the queue is full, the server responds with a `503` overloaded error. + +Set `OLLAMA_MAX_QUEUE` before starting the local server to change the maximum number of queued requests: + +```shell +OLLAMA_MAX_QUEUE=1024 ollama serve +``` + +See [How do I configure Ollama server?](/faq#how-do-i-configure-ollama-server) for operating-system-specific instructions for setting environment variables. + +## What is the difference between an API key and my Ollama Public Key? + +An **API key** authenticates a program that calls `https://ollama.com/api` directly. Create and manage API keys in [Ollama settings](https://ollama.com/settings/keys). See [Cloud API authentication](/cloud/api#authentication) for an example. + +Your **Ollama Public Key** identifies a local Ollama installation to ollama.com. It is used when you sign in locally to run Cloud models, push models, or pull private models. + +## Where can I find my Ollama Public Key? + +The Ollama Public Key is the public part of the key pair that lets your local Ollama instance communicate with [ollama.com](https://ollama.com). + +You need it to: + +- Push models to Ollama +- Pull private models to your machine +- Run models hosted in Ollama Cloud through your local Ollama installation + +### Add the key to your account + +Sign in from the Settings page in the macOS or Windows app, or sign in from the CLI: + +```shell +ollama signin +``` + +You can also copy and paste the public key on the [Ollama Keys](https://ollama.com/settings/keys) page. + +### Find the key on disk + +| Operating system | Path to `id_ed25519.pub` | +| --- | --- | +| macOS | `~/.ollama/id_ed25519.pub` | +| Linux | `/usr/share/ollama/.ollama/id_ed25519.pub` | +| Windows | `C:\Users\\.ollama\id_ed25519.pub` | + +Replace `` with your Windows user name. diff --git a/docs/cloud/model-lifecycle.mdx b/docs/cloud/model-lifecycle.mdx new file mode 100644 index 000000000..a54865a56 --- /dev/null +++ b/docs/cloud/model-lifecycle.mdx @@ -0,0 +1,59 @@ +--- +title: Cloud model lifecycle +description: Review upcoming and past Ollama Cloud model retirements and recommended replacements. +--- + +Ollama occasionally deprecates and retires older Cloud models as newer models become available. Tools and applications that depend on a retired model must be updated to use another model. + +Impacted users are notified before a model is retired. Cloud model retirement does not affect local models. + +## Upcoming retirements + +| Retirement date | Model | Recommended alternative | +| --- | --- | --- | +| July 31, 2026 | `minimax-m2.5` | `minimax-m2.7` | +| July 31, 2026 | `kimi-k2.5` | `kimi-k2.6` | + +## Past retirements + + + + | Model | Recommended alternative | + | --- | --- | + | `deepseek-v3.1:671b` | `deepseek-v4-flash` | + | `deepseek-v3.2` | `deepseek-v4-flash` | + | `devstral-2:123b` | `mistral-large-3:675b` | + | `devstral-small-2:24b` | | + | `ministral-3:14b` | | + | `ministral-3:3b` | | + | `ministral-3:8b` | | + | `gemini-3-flash-preview` | `minimax-m3` | + | `gemma3:12b` | `gemma4:31b` | + | `gemma3:27b` | `gemma4:31b` | + | `gemma3:4b` | `gemma4:31b` | + | `glm-4.7` | `glm-5.2` | + | `glm-5` | `glm-5.2` | + | `minimax-m2.1` | `minimax-m3` | + | `qwen3-coder-next` | `qwen3.5:397b` | + | `qwen3-coder:480b` | `qwen3.5:397b` | + + + + | Model | Recommended alternative | + | --- | --- | + | `rnj-1:8b` | | + + + + | Model | Recommended alternative | + | --- | --- | + | `kimi-k2-thinking` | `kimi-k2.6` | + | `kimi-k2:1t` | `kimi-k2.6` | + | `minimax-m2` | `minimax-m3` | + | `glm-4.6` | `glm-5.1` | + | `qwen3-next:80b` | `qwen3.5` | + | `qwen3-vl:235b` | `qwen3.5` | + | `qwen3-vl:235b-instruct` | `qwen3.5` | + | `cogito-2.1:671b` | `deepseek-v4-flash` | + + diff --git a/docs/cloud/models.mdx b/docs/cloud/models.mdx new file mode 100644 index 000000000..ffbd86768 --- /dev/null +++ b/docs/cloud/models.mdx @@ -0,0 +1,94 @@ +--- +title: Use Cloud models from Ollama +sidebarTitle: Cloud models +description: Run Ollama Cloud models from the CLI, the local Ollama API, or the official Python and JavaScript libraries. +--- + +Cloud models are automatically offloaded to Ollama Cloud while remaining available to local tools and integrations through Ollama. + +## Sign in + +Cloud models require an account on [ollama.com](https://ollama.com). Sign in or create an account from the CLI: + +```shell +ollama signin +``` + +Browse supported models in the [cloud model library](https://ollama.com/search?c=cloud). + +## Run a Cloud model + + + + +```shell +ollama run gpt-oss:120b-cloud +``` + + + + +Pull the Cloud model, then install the [Ollama Python library](https://github.com/ollama/ollama-python): + +```shell +ollama pull gpt-oss:120b-cloud +pip install ollama +``` + +```python +from ollama import Client + +client = Client() + +messages = [{"role": "user", "content": "Why is the sky blue?"}] + +for part in client.chat("gpt-oss:120b-cloud", messages=messages, stream=True): + print(part["message"]["content"], end="", flush=True) +``` + + + + +Pull the Cloud model, then install the [Ollama JavaScript library](https://github.com/ollama/ollama-js): + +```shell +ollama pull gpt-oss:120b-cloud +npm i ollama +``` + +```typescript +import { Ollama } from "ollama"; + +const ollama = new Ollama(); +const response = await ollama.chat({ + model: "gpt-oss:120b-cloud", + messages: [{ role: "user", content: "Explain quantum computing" }], + stream: true, +}); + +for await (const part of response) { + process.stdout.write(part.message.content); +} +``` + + + + +Pull the Cloud model, then call it through the local Ollama API: + +```shell +ollama pull gpt-oss:120b-cloud +``` + +```shell +curl http://localhost:11434/api/chat -d '{ + "model": "gpt-oss:120b-cloud", + "messages": [{"role": "user", "content": "Why is the sky blue?"}], + "stream": false +}' +``` + + + + +To use Cloud without a local Ollama installation, call the [Cloud API directly](/cloud/api). diff --git a/docs/docs.json b/docs/docs.json index 727e3ef26..8c848dee6 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -110,8 +110,7 @@ "group": "Get started", "pages": [ "index", - "quickstart", - "/cloud" + "quickstart" ] }, { @@ -127,19 +126,66 @@ ] }, { - "group": "More information", + "group": "Sample projects", + "pages": [ + "/sample-projects/research-brief-agent" + ] + } + ] + }, + { + "tab": "Cloud", + "groups": [ + { + "group": "Get started", + "pages": [ + "/cloud", + "/cloud/models", + "/cloud/api" + ] + }, + { + "group": "Operations", + "pages": [ + "/cloud/model-lifecycle", + "/cloud/faq" + ] + } + ] + }, + { + "tab": "Local", + "groups": [ + { + "group": "Get started", + "pages": [ + "/local", + "/macos", + "/linux", + "/windows", + "/docker" + ] + }, + { + "group": "Run and configure", "pages": [ "/cli", - "/modelfile", - "/context-length", - "/linux", - "/macos", - "/windows", - "/docker", + "/context-length" + ] + }, + { + "group": "Customize models", + "pages": [ "/import", - "/faq", + "/modelfile" + ] + }, + { + "group": "Hardware and support", + "pages": [ "/gpu", - "/troubleshooting" + "/troubleshooting", + "/faq" ] } ] diff --git a/docs/faq.mdx b/docs/faq.mdx index c2f3b4f57..92a7404da 100644 --- a/docs/faq.mdx +++ b/docs/faq.mdx @@ -1,7 +1,11 @@ --- -title: FAQ +title: Local FAQ +sidebarTitle: FAQ +description: Frequently asked questions about installing, configuring, and running Ollama locally. --- +For questions about accounts, authentication, and hosted models, see the [Cloud FAQ](/cloud/faq). + ## How can I upgrade Ollama? Ollama on macOS and Windows will automatically download updates. Click on the taskbar or menubar item and then click "Restart to update" to apply the update. Updates can also be installed by downloading the latest version [manually](https://ollama.com/download/). @@ -156,10 +160,6 @@ docker build -t ollama-with-ca . docker run -d -e HTTPS_PROXY=https://my.proxy.example.com -p 11434:11434 ollama-with-ca ``` -## Does Ollama send my prompts and answers back to ollama.com? - -Ollama runs locally. We don't see your prompts or data when you run locally. When using cloud-hosted models, we process your prompts and responses to provide the service but do not store or log that content and never train on it. We collect basic account info and limited usage metadata to provide the service that does not include prompt or response content. We don't sell your data. You can delete your account anytime. - ## How do I disable Ollama Cloud features? Ollama can run in local only mode by disabling Ollama's cloud features. By turning off Ollama's cloud features, you will lose the ability to use Ollama's cloud models and web search. @@ -317,10 +317,6 @@ Alternatively, you can change the amount of time all models are loaded into memo The `keep_alive` API parameter with the `/api/generate` and `/api/chat` API endpoints will override the `OLLAMA_KEEP_ALIVE` setting. -## How do I manage the maximum number of requests the Ollama server can queue? - -If too many requests are sent to the server, it will respond with a 503 error indicating the server is overloaded. You can adjust how many requests may be queued by setting `OLLAMA_MAX_QUEUE`. - ## How does Ollama handle concurrent requests? Ollama supports two levels of concurrent processing. If your system has sufficient available memory (system memory when using CPU inference, or VRAM for GPU inference) then multiple models can be loaded at the same time. For a given model, if there is sufficient available memory when the model is loaded, it is configured to allow parallel request processing. @@ -368,40 +364,6 @@ How much the cache quantization impacts the model's response quality will depend You may need to experiment with different quantization types to find the best balance between memory usage and quality. -## Where can I find my Ollama Public Key? - -Your **Ollama Public Key** is the public part of the key pair that lets your local Ollama instance talk to [ollama.com](https://ollama.com). - -You'll need it to: -* Push models to Ollama -* Pull private models from Ollama to your machine -* Run models hosted in [Ollama Cloud](https://ollama.com/cloud) - -### How to Add the Key - -* **Sign-in via the Settings page** in the **Mac** and **Windows App** - -* **Sign‑in via CLI** - -```shell -ollama signin -``` - -* **Manually copy & paste** the key on the **Ollama Keys** page: -[https://ollama.com/settings/keys](https://ollama.com/settings/keys) - -### Where the Ollama Public Key lives - -| OS | Path to `id_ed25519.pub` | -| :- | :- | -| macOS | `~/.ollama/id_ed25519.pub` | -| Linux | `/usr/share/ollama/.ollama/id_ed25519.pub` | -| Windows | `C:\Users\\.ollama\id_ed25519.pub` | - - - Replace <username> with your actual Windows user name. - - ## How can I stop Ollama from starting when I login to my computer? Ollama for Windows and macOS register as a login item during installation. You can disable this if you prefer not to have Ollama automatically start. Ollama will respect this setting across upgrades, unless you uninstall the application. diff --git a/docs/index.mdx b/docs/index.mdx index 5d7e01a5a..f9c9e2641 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -1,26 +1,31 @@ --- title: Ollama documentation sidebarTitle: Welcome +description: Learn what Ollama can do, choose cloud or local models, and find the right guide, integration, or API reference. --- -Start building with open models. +Build with open models in Ollama Cloud or on your own hardware. -Follow the [quickstart](/quickstart), then choose a model, integration, or API. +Follow the [quickstart](/quickstart), then choose the environment that matches your needs. -## Models +## Choose where models run -Run models locally or use larger models in Ollama's cloud. +Cloud and local models use the same Ollama tools and API shapes. The main difference is where inference runs. - - Find models for chat, coding, vision, embeddings, and reasoning. + + Run larger models without managing local compute, either from Ollama or through the Cloud API. - - Run larger models on Ollama's Cloud without the download. + + Install Ollama and run models on macOS, Windows, Linux, or Docker. +## What you can build + +Ollama supports [streaming](/capabilities/streaming), [tool calling](/capabilities/tool-calling), [structured outputs](/capabilities/structured-outputs), [vision](/capabilities/vision), [embeddings](/capabilities/embeddings), [thinking](/capabilities/thinking), and [web search](/capabilities/web-search). + ## Next steps Connect Ollama to an app, or build with the API. @@ -30,8 +35,12 @@ Connect Ollama to an app, or build with the API. Connect Ollama to an app, editor, or agent. - - Learn the local and cloud base URLs, then send a request with `curl`. + + Compare local and cloud base URLs, then send your first request. + + + + Find models for chat, coding, vision, embeddings, and reasoning. @@ -53,4 +62,12 @@ Connect Ollama to an app, or build with the API. Join the Ollama subreddit. + + + Join the Ollama X (Twitter). + + + + Join the Ollama GitHub. + diff --git a/docs/local.mdx b/docs/local.mdx new file mode 100644 index 000000000..dafc22b59 --- /dev/null +++ b/docs/local.mdx @@ -0,0 +1,57 @@ +--- +title: Run Ollama locally +sidebarTitle: Overview +description: Install, configure, and run Ollama models on your own macOS, Windows, Linux, or Docker environment. +--- + +Run models on your own hardware with Ollama. Local inference keeps model execution on the machine or infrastructure you control and does not require an Ollama account. + +## Install Ollama + +Choose the installation guide for your environment. + + + + Install the Ollama app on Apple silicon or Intel hardware. + + + + Install the native Windows application. + + + + Install Ollama with the install script or a manual package. + + + + Run Ollama in a container with CPU or GPU acceleration. + + + +## Run a local model + +After installation, start a model from the terminal: + +```shell +ollama run gemma4 +``` + +Ollama also serves its local API at `http://localhost:11434/api` by default. + +```shell +curl http://localhost:11434/api/chat -d '{ + "model": "gemma4", + "messages": [{"role": "user", "content": "Why is the sky blue?"}], + "stream": false +}' +``` + +## Configure your environment + +- Use the [CLI reference](/cli) to run, download, copy, and remove models. +- Adjust the [context length](/context-length) for agents and other long-context workloads. +- Review [hardware support](/gpu) for GPU compatibility and acceleration. +- [Import a model](/import) or create a customized model with a [Modelfile](/modelfile). +- Use [local-only mode](/faq#how-do-i-disable-ollama-cloud-features) to disable Ollama Cloud features. + +For failures, start with [Troubleshooting](/troubleshooting). diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx index c985d6d80..4f3f54ea9 100644 --- a/docs/quickstart.mdx +++ b/docs/quickstart.mdx @@ -1,10 +1,27 @@ --- title: Quickstart +description: Choose Ollama Cloud or a local installation and run your first model. --- -Install Ollama and get your first response. +Get your first response from a cloud or local model. The Ollama CLI and API work with both. -## 1. Download Ollama +## Choose an environment + + + + Use larger models without providing your own GPU. Start from the Ollama CLI or call the Cloud API directly. + + + + Run models on your own hardware. Start by installing Ollama for your operating system. + + + +## Run a model from the CLI + +This path works with local models and cloud models. + +### 1. Download Ollama Ollama runs on macOS, Windows, and Linux. @@ -16,7 +33,7 @@ Ollama runs on macOS, Windows, and Linux. Download Ollama -## 2. Open the menu +### 2. Open the menu Run `ollama` in your terminal to open the interactive menu: @@ -29,7 +46,7 @@ From the menu you can: - **Run a model** - Start an interactive chat - **Launch tools** - [Claude Code](/integrations/claude-code), [OpenClaw](/integrations/openclaw), [VS Code](/integrations/vscode), and more -## 3. Start a chat +### 3. Start a chat Run a model to start your first chat. @@ -37,9 +54,10 @@ Run a model to start your first chat. ollama run gemma4 ``` -Cloud models work the same way: +Or sign in and run a cloud model: ```shell +ollama signin ollama run gemma4:cloud ``` @@ -57,4 +75,4 @@ To leave the chat, type: ## Next steps -Use a model with an [integration](/integrations), make an [API request](/api/introduction), or browse more [models](https://ollama.com/search). +Learn about [Cloud](/cloud) or [Local](/local), use a model with an [integration](/integrations), make an [API request](/api/introduction), or browse [models](https://ollama.com/search). diff --git a/docs/sample-projects/research-brief-agent.mdx b/docs/sample-projects/research-brief-agent.mdx new file mode 100644 index 000000000..e10839bf1 --- /dev/null +++ b/docs/sample-projects/research-brief-agent.mdx @@ -0,0 +1,306 @@ +--- +title: Build a research brief agent +sidebarTitle: Research brief agent +description: Build an Ollama Cloud agent that searches the web, reads primary sources, and produces a cited research brief. +--- + +Build an agent that researches a question and turns its findings into a cited decision brief. This is useful for market research, policy summaries, product comparisons, event planning, and other tasks where current sources matter. + +The project uses an Ollama Cloud model for reasoning and the Ollama web search and web fetch APIs for research. It runs entirely through Ollama Cloud, so you do not need a local model or GPU. + +## What you will build + +Given a question such as: + +> What have four-day workweek pilots since 2022 reported about employee wellbeing and business performance? + +the agent will: + +1. Turn the question into several focused searches. +2. Search the web and choose promising results. +3. Fetch source pages for more context. +4. Compare claims across sources. +5. Write a brief with links, caveats, and suggested follow-up questions. + +The example uses `gpt-oss:120b`, but you can choose another tool-capable model returned by the Cloud API. + +## Before you begin + +You need: + +- Python 3.10 or later +- An [Ollama account](https://ollama.com) +- An [Ollama API key](https://ollama.com/settings/keys) + +The API key gives the script access to both the Cloud model and the [web search tools](/capabilities/web-search). Treat it like a password and do not add it to source control. + +## 1. Set up the project + +Create a project directory and a Python virtual environment: + + + + +```shell +mkdir research-brief-agent +cd research-brief-agent +python3 -m venv .venv +source .venv/bin/activate +``` + + + + +```powershell +mkdir research-brief-agent +cd research-brief-agent +py -m venv .venv +.venv\Scripts\Activate.ps1 +``` + + + + +Install the Ollama Python library: + +```shell +pip install --upgrade ollama +``` + +Set your API key for the current terminal session: + + + + +```shell +export OLLAMA_API_KEY=your_api_key +``` + + + + +```powershell +$env:OLLAMA_API_KEY="your_api_key" +``` + + + + + + Environment variables set this way last only for the current terminal session. Use your operating system's secret manager for a persistent setup. + + +## 2. Check Cloud access + +List the models available to your account: + +```shell +curl https://ollama.com/api/tags \ + -H "Authorization: Bearer $OLLAMA_API_KEY" +``` + +Look for `gpt-oss:120b` in the response. If it is not available, choose another Cloud model that supports tool calling and set its name with `OLLAMA_MODEL`: + + + + +```shell +export OLLAMA_MODEL=your_model_name +``` + + + + +```powershell +$env:OLLAMA_MODEL="your_model_name" +``` + + + + +## 3. Create the agent + +Save the following as `research_agent.py`: + +```python +import os +import sys + +from ollama import Client, web_fetch, web_search + + +MODEL = os.getenv("OLLAMA_MODEL", "gpt-oss:120b") +MAX_TOOL_ROUNDS = 8 + +SYSTEM_PROMPT = """You are a careful research agent. + +Research the user's question before answering. Search broadly, then fetch the +most useful pages. Prefer primary sources, original studies, official reports, +and sources that clearly explain their methods. + +Your final answer must contain: +1. An executive summary +2. Key findings, including disagreements between sources +3. Limitations and missing evidence +4. Practical next steps +5. A Sources section with Markdown links + +Attach a source link to every important factual claim. Never invent a citation. +If the available evidence does not support a conclusion, say so explicitly. +""" + + +def run_tool(name: str, arguments: dict) -> str: + """Run one tool selected by the model and return text for the next turn.""" + tools = { + "web_search": web_search, + "web_fetch": web_fetch, + } + + tool = tools.get(name) + if tool is None: + return f"Unknown tool: {name}" + + print(f"Tool: {name}({arguments})") + result = tool(**arguments) + + # Large pages can crowd useful evidence out of the model's context. + return str(result)[:12000] + + +def research(question: str) -> str: + api_key = os.environ.get("OLLAMA_API_KEY") + if not api_key: + raise RuntimeError("Set OLLAMA_API_KEY before running the agent.") + + client = Client( + host="https://ollama.com", + headers={"Authorization": f"Bearer {api_key}"}, + ) + + messages = [ + {"role": "system", "content": SYSTEM_PROMPT}, + {"role": "user", "content": question}, + ] + + for _ in range(MAX_TOOL_ROUNDS): + response = client.chat( + model=MODEL, + messages=messages, + tools=[web_search, web_fetch], + think=True, + ) + messages.append(response.message) + + if not response.message.tool_calls: + return response.message.content + + for call in response.message.tool_calls: + name = call.function.name + result = run_tool(name, call.function.arguments) + messages.append( + { + "role": "tool", + "tool_name": name, + "content": result, + } + ) + + # Force a final report if the model uses the full research budget. + messages.append( + { + "role": "user", + "content": "Stop researching and write the final cited brief now.", + } + ) + response = client.chat(model=MODEL, messages=messages, think=True) + return response.message.content + + +if __name__ == "__main__": + default_question = ( + "What have four-day workweek pilots since 2022 reported about " + "employee wellbeing and business performance?" + ) + question = " ".join(sys.argv[1:]) or default_question + print(research(question)) +``` + +The model receives two tools as Python functions. Ollama converts those functions into tool definitions, the Cloud model decides when and how to call them, and the script returns each tool result to the model. The loop ends when the model produces a response without another tool call. + +`MAX_TOOL_ROUNDS` prevents an open-ended research loop. The final request removes the tools and asks for a report if the agent uses its entire tool budget. + +## 4. Run the project + +Run the agent with the example research question: + +```shell +python research_agent.py +``` + +Or provide your own question: + +```shell +python research_agent.py "What evidence supports later high school start times?" +``` + +During the run, the script prints each tool call. A typical trace looks like this: + +```text +Tool: web_search({'query': 'four-day workweek pilot 2022 study results'}) +Tool: web_search({'query': 'four-day week trial company revenue retention report'}) +Tool: web_fetch({'url': 'https://example.org/report'}) +``` + +Search queries and sources will vary between runs. That is expected: the model chooses its next action from the evidence it has already gathered. + +## 5. Review the result + +Expect a Markdown report with this general shape: + +```text +# Research brief + +## Executive summary +A concise answer to the research question. + +## Key findings +Findings grouped by theme, with links attached to factual claims. + +## Limitations +Gaps in the available evidence, methodology concerns, and conflicting results. + +## Practical next steps +Actions or questions that follow from the evidence. + +## Sources +A list of the pages used in the report. +``` + +The first run should produce a useful draft, not an unquestionable final answer. Check that links open, quoted numbers match their sources, and the report distinguishes published evidence from the model's interpretation. + + + Web results can be incomplete, outdated, or wrong. Review the original sources before using the brief for medical, legal, financial, employment, or other high-impact decisions. + + +## What happens at each stage + +| Stage | What the Cloud model does | What you should expect | +| --- | --- | --- | +| Plan | Breaks the question into searchable claims | Several queries covering different aspects of the topic | +| Search | Calls `web_search` and evaluates result snippets | A visible tool trace; some searches may be discarded | +| Read | Calls `web_fetch` for promising pages | More detailed evidence from a smaller set of sources | +| Compare | Looks for agreement, conflicts, and missing context | Findings that separate strong evidence from uncertainty | +| Synthesize | Writes the requested report | A readable brief with citations, caveats, and next steps | + +## Improve the agent + +Try these changes after the basic project works: + +- Change `SYSTEM_PROMPT` to require a particular audience, length, or report format. +- Ask the agent to prefer sources from specific domains or a date range. +- Increase `MAX_TOOL_ROUNDS` for broader research, or decrease it for faster, more focused runs. +- Save the final string to a Markdown file for sharing. +- Add a human approval step before the agent fetches unfamiliar domains. + +See [Tool calling](/capabilities/tool-calling) for more agent-loop patterns and [Web search](/capabilities/web-search) for the complete search and fetch interfaces. From 8ca05a6027bf45654917c1524254e1a84134476a Mon Sep 17 00:00:00 2001 From: Anna Rahn Date: Tue, 6 Oct 2026 16:35:27 -0700 Subject: [PATCH 2/8] reorganizing the docs folder, adding error handling to the sample project, changing wording --- docs/README.md | 18 +- docs/api.md | 10 +- docs/cloud/faq.mdx | 6 +- docs/{cloud.mdx => cloud/index.mdx} | 2 +- docs/docs.json | 174 ++++++-- docs/{ => guide}/capabilities/embeddings.mdx | 0 docs/{ => guide}/capabilities/streaming.mdx | 0 .../capabilities/structured-outputs.mdx | 0 docs/{ => guide}/capabilities/thinking.mdx | 0 .../{ => guide}/capabilities/tool-calling.mdx | 0 docs/{ => guide}/capabilities/vision.mdx | 0 docs/{ => guide}/capabilities/web-search.mdx | 0 docs/{ => guide}/quickstart.mdx | 0 .../sample-projects/research-report-agent.mdx | 398 ++++++++++++++++++ docs/index.mdx | 12 +- docs/integrations/claude-code.mdx | 4 +- docs/integrations/cline.mdx | 2 +- docs/integrations/copilot-cli.mdx | 2 +- docs/integrations/droid.mdx | 2 +- docs/integrations/openclaw.mdx | 2 +- docs/integrations/opencode.mdx | 2 +- docs/integrations/roo-code.mdx | 2 +- docs/integrations/vscode.mdx | 2 +- docs/{ => local}/cli.mdx | 0 docs/{ => local}/context-length.mdx | 2 +- docs/{ => local}/docker.mdx | 0 docs/{ => local}/faq.mdx | 2 +- docs/{ => local}/gpu.mdx | 2 +- docs/{ => local}/import.mdx | 0 docs/{local.mdx => local/index.mdx} | 20 +- docs/{ => local}/linux.mdx | 0 docs/{ => local}/macos.mdx | 0 docs/{ => local}/modelfile.mdx | 0 docs/{ => local}/template.mdx | 0 docs/{ => local}/troubleshooting.mdx | 0 docs/{ => local}/windows.mdx | 0 docs/sample-projects/research-brief-agent.mdx | 306 -------------- 37 files changed, 575 insertions(+), 395 deletions(-) rename docs/{cloud.mdx => cloud/index.mdx} (88%) rename docs/{ => guide}/capabilities/embeddings.mdx (100%) rename docs/{ => guide}/capabilities/streaming.mdx (100%) rename docs/{ => guide}/capabilities/structured-outputs.mdx (100%) rename docs/{ => guide}/capabilities/thinking.mdx (100%) rename docs/{ => guide}/capabilities/tool-calling.mdx (100%) rename docs/{ => guide}/capabilities/vision.mdx (100%) rename docs/{ => guide}/capabilities/web-search.mdx (100%) rename docs/{ => guide}/quickstart.mdx (100%) create mode 100644 docs/guide/sample-projects/research-report-agent.mdx rename docs/{ => local}/cli.mdx (100%) rename docs/{ => local}/context-length.mdx (95%) rename docs/{ => local}/docker.mdx (100%) rename docs/{ => local}/faq.mdx (99%) rename docs/{ => local}/gpu.mdx (99%) rename docs/{ => local}/import.mdx (100%) rename docs/{local.mdx => local/index.mdx} (58%) rename docs/{ => local}/linux.mdx (100%) rename docs/{ => local}/macos.mdx (100%) rename docs/{ => local}/modelfile.mdx (100%) rename docs/{ => local}/template.mdx (100%) rename docs/{ => local}/troubleshooting.mdx (100%) rename docs/{ => local}/windows.mdx (100%) delete mode 100644 docs/sample-projects/research-brief-agent.mdx diff --git a/docs/README.md b/docs/README.md index f11addb3f..c2caa9e51 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,29 +2,29 @@ ### Getting started -* [Quickstart](https://docs.ollama.com/quickstart) +* [Quickstart](https://docs.ollama.com/guide/quickstart) * [Ollama Cloud](https://docs.ollama.com/cloud) * [Run Ollama locally](https://docs.ollama.com/local) * [Examples](./examples.md) ### Local -* [macOS](https://docs.ollama.com/macos) -* [Linux](https://docs.ollama.com/linux) -* [Windows](https://docs.ollama.com/windows) -* [Docker](https://docs.ollama.com/docker) -* [Importing models](https://docs.ollama.com/import) +* [macOS](https://docs.ollama.com/local/macos) +* [Linux](https://docs.ollama.com/local/linux) +* [Windows](https://docs.ollama.com/local/windows) +* [Docker](https://docs.ollama.com/local/docker) +* [Importing models](https://docs.ollama.com/local/import) ### Reference * [API Reference](https://docs.ollama.com/api) -* [Modelfile Reference](https://docs.ollama.com/modelfile) +* [Modelfile Reference](https://docs.ollama.com/local/modelfile) * [OpenAI Compatibility](https://docs.ollama.com/api/openai-compatibility) * [Anthropic Compatibility](./api/anthropic-compatibility.mdx) ### Resources -* [Troubleshooting Guide](https://docs.ollama.com/troubleshooting) -* [Local FAQ](https://docs.ollama.com/faq) +* [Troubleshooting Guide](https://docs.ollama.com/local/troubleshooting) +* [Local FAQ](https://docs.ollama.com/local/faq) * [Cloud FAQ](https://docs.ollama.com/cloud/faq) * [Development guide](./development.md) diff --git a/docs/api.md b/docs/api.md index 95cac42ca..26d9247e3 100644 --- a/docs/api.md +++ b/docs/api.md @@ -50,7 +50,7 @@ Generate a response for a given prompt with a provided model. This is a streamin Advanced parameters (optional): - `format`: the format to return a response in. Format can be `json` or a JSON schema -- `options`: additional model parameters listed in the documentation for the [Modelfile](./modelfile.mdx#valid-parameters-and-values) such as `temperature` +- `options`: additional model parameters listed in the documentation for the [Modelfile](./local/modelfile.mdx#valid-parameters-and-values) such as `temperature` - `system`: system message to (overrides what is defined in the `Modelfile`) - `template`: the prompt template to use (overrides what is defined in the `Modelfile`) - `stream`: if `false` the response will be returned as a single response object, rather than a stream of objects @@ -508,7 +508,7 @@ The `message` object has the following fields: Advanced parameters (optional): - `format`: the format to return a response in. Format can be `json` or a JSON schema. -- `options`: additional model parameters listed in the documentation for the [Modelfile](./modelfile.mdx#valid-parameters-and-values) such as `temperature` +- `options`: additional model parameters listed in the documentation for the [Modelfile](./local/modelfile.mdx#valid-parameters-and-values) such as `temperature` - `stream`: if `false` the response will be returned as a single response object, rather than a stream of objects - `keep_alive`: controls how long the model will stay loaded into memory following the request (default: `5m`) @@ -1192,7 +1192,7 @@ If you are creating a model from a safetensors directory or from a GGUF file, yo - `parser`: (optional) the name of the parser for the model - `license`: (optional) a string or list of strings containing the license or licenses for the model - `system`: (optional) a string containing the system prompt for the model -- `parameters`: (optional) a dictionary of parameters for the model (see [Modelfile](./modelfile.mdx#valid-parameters-and-values) for a list of parameters) +- `parameters`: (optional) a dictionary of parameters for the model (see [Modelfile](./local/modelfile.mdx#valid-parameters-and-values) for a list of parameters) - `messages`: (optional) a list of message objects used to create a conversation - `stream`: (optional) if `false` the response will be returned as a single response object, rather than a stream of objects - `quantize` (optional): quantize a non-quantized (e.g. float16) model @@ -1701,7 +1701,7 @@ Generate embeddings from a model Advanced parameters: - `truncate`: truncates the end of each input to fit within context length. Returns error if `false` and context length is exceeded. Defaults to `true` -- `options`: additional model parameters listed in the documentation for the [Modelfile](./modelfile.mdx#valid-parameters-and-values) such as `temperature` +- `options`: additional model parameters listed in the documentation for the [Modelfile](./local/modelfile.mdx#valid-parameters-and-values) such as `temperature` - `keep_alive`: controls how long the model will stay loaded into memory following the request (default: `5m`) - `dimensions`: number of dimensions for the embedding @@ -1820,7 +1820,7 @@ Generate embeddings from a model Advanced parameters: -- `options`: additional model parameters listed in the documentation for the [Modelfile](./modelfile.mdx#valid-parameters-and-values) such as `temperature` +- `options`: additional model parameters listed in the documentation for the [Modelfile](./local/modelfile.mdx#valid-parameters-and-values) such as `temperature` - `keep_alive`: controls how long the model will stay loaded into memory following the request (default: `5m`) ### Examples diff --git a/docs/cloud/faq.mdx b/docs/cloud/faq.mdx index e5b2a1a61..41025e415 100644 --- a/docs/cloud/faq.mdx +++ b/docs/cloud/faq.mdx @@ -4,7 +4,7 @@ sidebarTitle: FAQ description: Frequently asked questions about Ollama Cloud accounts, authentication, privacy, and requests. --- -For questions about installation, hardware, and the local Ollama server, see the [Local FAQ](/faq). +For questions about installation, hardware, and the local Ollama server, see the [Local FAQ](/local/faq). ## Does Ollama send my prompts and answers back to ollama.com? @@ -12,7 +12,7 @@ Ollama runs locally. We don't see your prompts or data when you run local models When you use Cloud models, Ollama processes your prompts and responses to provide the service but does not store or log that content and never trains on it. Ollama collects basic account information and limited usage metadata that does not include prompt or response content. Ollama does not sell your data, and you can delete your account at any time. -To prevent a local Ollama installation from using Cloud models and web search, enable [local-only mode](/faq#how-do-i-disable-ollama-cloud-features). +To prevent a local Ollama installation from using Cloud models and web search, enable [local-only mode](/local/faq#how-do-i-disable-ollama-cloud-features). ## How do I manage the maximum number of requests the Ollama server can queue? @@ -24,7 +24,7 @@ Set `OLLAMA_MAX_QUEUE` before starting the local server to change the maximum nu OLLAMA_MAX_QUEUE=1024 ollama serve ``` -See [How do I configure Ollama server?](/faq#how-do-i-configure-ollama-server) for operating-system-specific instructions for setting environment variables. +See [How do I configure Ollama server?](/local/faq#how-do-i-configure-ollama-server) for operating-system-specific instructions for setting environment variables. ## What is the difference between an API key and my Ollama Public Key? diff --git a/docs/cloud.mdx b/docs/cloud/index.mdx similarity index 88% rename from docs/cloud.mdx rename to docs/cloud/index.mdx index 6f34bd658..d82f785d3 100644 --- a/docs/cloud.mdx +++ b/docs/cloud/index.mdx @@ -30,7 +30,7 @@ Follow the [Cloud API guide](/cloud/api) to call `https://ollama.com/api` direct ## Local only -Use [Local](/local) when you want inference to run on hardware you control. Ollama can also run in [local-only mode](/faq#how-do-i-disable-ollama-cloud-features) with Cloud features disabled. +Use [Local](/local) when you want inference to run on your own hardware. Ollama can also run in [local-only mode](/local/faq#how-do-i-disable-ollama-cloud-features) with Cloud features disabled. ## Retirements diff --git a/docs/docs.json b/docs/docs.json index 8c848dee6..50cd98b49 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -70,7 +70,7 @@ }, { "source": "/gpu.mdx", - "destination": "/gpu" + "destination": "/local/gpu" }, { "source": "/integrations/vscode.mdx", @@ -78,7 +78,7 @@ }, { "source": "/troubleshooting.mdx", - "destination": "/troubleshooting" + "destination": "/local/troubleshooting" }, { "source": "/openai", @@ -99,6 +99,94 @@ { "source": "/integrations/poolside", "destination": "/integrations/pool" + }, + { + "source": "/quickstart", + "destination": "/guide/quickstart" + }, + { + "source": "/capabilities/streaming", + "destination": "/guide/capabilities/streaming" + }, + { + "source": "/capabilities/thinking", + "destination": "/guide/capabilities/thinking" + }, + { + "source": "/capabilities/structured-outputs", + "destination": "/guide/capabilities/structured-outputs" + }, + { + "source": "/capabilities/vision", + "destination": "/guide/capabilities/vision" + }, + { + "source": "/capabilities/embeddings", + "destination": "/guide/capabilities/embeddings" + }, + { + "source": "/capabilities/tool-calling", + "destination": "/guide/capabilities/tool-calling" + }, + { + "source": "/capabilities/web-search", + "destination": "/guide/capabilities/web-search" + }, + { + "source": "/sample-projects/research-brief-agent", + "destination": "/guide/sample-projects/research-report-agent" + }, + { + "source": "/guide/sample-projects/research-brief-agent", + "destination": "/guide/sample-projects/research-report-agent" + }, + { + "source": "/cli", + "destination": "/local/cli" + }, + { + "source": "/context-length", + "destination": "/local/context-length" + }, + { + "source": "/macos", + "destination": "/local/macos" + }, + { + "source": "/linux", + "destination": "/local/linux" + }, + { + "source": "/windows", + "destination": "/local/windows" + }, + { + "source": "/docker", + "destination": "/local/docker" + }, + { + "source": "/import", + "destination": "/local/import" + }, + { + "source": "/modelfile", + "destination": "/local/modelfile" + }, + { + "source": "/gpu", + "destination": "/local/gpu" + }, + { + "source": "/troubleshooting", + "destination": "/local/troubleshooting" + }, + { + "source": "/faq", + "destination": "/local/faq" + }, + { + "source": "/template", + "destination": "/local/template" } ], "navigation": { @@ -110,45 +198,25 @@ "group": "Get started", "pages": [ "index", - "quickstart" + "/guide/quickstart" ] }, { "group": "Capabilities", "pages": [ - "/capabilities/streaming", - "/capabilities/thinking", - "/capabilities/structured-outputs", - "/capabilities/vision", - "/capabilities/embeddings", - "/capabilities/tool-calling", - "/capabilities/web-search" + "/guide/capabilities/streaming", + "/guide/capabilities/thinking", + "/guide/capabilities/structured-outputs", + "/guide/capabilities/vision", + "/guide/capabilities/embeddings", + "/guide/capabilities/tool-calling", + "/guide/capabilities/web-search" ] }, { "group": "Sample projects", "pages": [ - "/sample-projects/research-brief-agent" - ] - } - ] - }, - { - "tab": "Cloud", - "groups": [ - { - "group": "Get started", - "pages": [ - "/cloud", - "/cloud/models", - "/cloud/api" - ] - }, - { - "group": "Operations", - "pages": [ - "/cloud/model-lifecycle", - "/cloud/faq" + "/guide/sample-projects/research-report-agent" ] } ] @@ -159,33 +227,53 @@ { "group": "Get started", "pages": [ - "/local", - "/macos", - "/linux", - "/windows", - "/docker" + "/local/index", + "/local/macos", + "/local/linux", + "/local/windows", + "/local/docker" ] }, { "group": "Run and configure", "pages": [ - "/cli", - "/context-length" + "/local/cli", + "/local/context-length" ] }, { "group": "Customize models", "pages": [ - "/import", - "/modelfile" + "/local/import", + "/local/modelfile" ] }, { "group": "Hardware and support", "pages": [ - "/gpu", - "/troubleshooting", - "/faq" + "/local/gpu", + "/local/troubleshooting", + "/local/faq" + ] + } + ] + }, + { + "tab": "Cloud", + "groups": [ + { + "group": "Get started", + "pages": [ + "/cloud/index", + "/cloud/models", + "/cloud/api" + ] + }, + { + "group": "Operations", + "pages": [ + "/cloud/model-lifecycle", + "/cloud/faq" ] } ] diff --git a/docs/capabilities/embeddings.mdx b/docs/guide/capabilities/embeddings.mdx similarity index 100% rename from docs/capabilities/embeddings.mdx rename to docs/guide/capabilities/embeddings.mdx diff --git a/docs/capabilities/streaming.mdx b/docs/guide/capabilities/streaming.mdx similarity index 100% rename from docs/capabilities/streaming.mdx rename to docs/guide/capabilities/streaming.mdx diff --git a/docs/capabilities/structured-outputs.mdx b/docs/guide/capabilities/structured-outputs.mdx similarity index 100% rename from docs/capabilities/structured-outputs.mdx rename to docs/guide/capabilities/structured-outputs.mdx diff --git a/docs/capabilities/thinking.mdx b/docs/guide/capabilities/thinking.mdx similarity index 100% rename from docs/capabilities/thinking.mdx rename to docs/guide/capabilities/thinking.mdx diff --git a/docs/capabilities/tool-calling.mdx b/docs/guide/capabilities/tool-calling.mdx similarity index 100% rename from docs/capabilities/tool-calling.mdx rename to docs/guide/capabilities/tool-calling.mdx diff --git a/docs/capabilities/vision.mdx b/docs/guide/capabilities/vision.mdx similarity index 100% rename from docs/capabilities/vision.mdx rename to docs/guide/capabilities/vision.mdx diff --git a/docs/capabilities/web-search.mdx b/docs/guide/capabilities/web-search.mdx similarity index 100% rename from docs/capabilities/web-search.mdx rename to docs/guide/capabilities/web-search.mdx diff --git a/docs/quickstart.mdx b/docs/guide/quickstart.mdx similarity index 100% rename from docs/quickstart.mdx rename to docs/guide/quickstart.mdx diff --git a/docs/guide/sample-projects/research-report-agent.mdx b/docs/guide/sample-projects/research-report-agent.mdx new file mode 100644 index 000000000..7a796f0a8 --- /dev/null +++ b/docs/guide/sample-projects/research-report-agent.mdx @@ -0,0 +1,398 @@ +--- +title: Build a research report agent +sidebarTitle: Research report agent +description: Build an Ollama Cloud agent that searches the web, reads primary sources, and produces a cited research report. +--- + +Build an agent that researches a question and turns its findings into a cited decision report. This is useful for market research, policy summaries, product comparisons, event planning, and other tasks where current sources matter. + +The project uses an Ollama Cloud model for reasoning and the Ollama web search and web fetch APIs for research. Inference runs in Ollama Cloud, so you do not need to download the 120B model weights or provide a local GPU. Your local Ollama installation sends requests to the Cloud model. + +## What you will build + +Given a question such as: + +> What have four-day workweek pilots since 2022 reported about employee wellbeing and business performance? + +the agent will: + +1. Turn the question into several focused searches. +2. Search the web and choose promising results. +3. Fetch source pages for more context. +4. Compare claims across sources. +5. Write a report with links, caveats, and suggested follow-up questions. + +The tutorial uses `gpt-oss:120b-cloud` throughout. + +## Before you begin + +You need: + +- [Ollama installed](https://ollama.com/download) +- Python 3.10 or later +- An [Ollama account](https://ollama.com) +- An [Ollama API key](https://ollama.com/settings/keys) + +Signing in to Ollama gives your local installation access to the Cloud model. The API key gives the script access to the [web search tools](/guide/capabilities/web-search). Treat the API key like a password and do not add it to source control. + +## 1. Set up the project + +Create a project directory and a Python virtual environment: + + + + +```shell +mkdir research-report-agent +cd research-report-agent +python3 -m venv .venv +source .venv/bin/activate +``` + + + + +```powershell +mkdir research-report-agent +cd research-report-agent +py -m venv .venv +.venv\Scripts\Activate.ps1 +``` + + + + +Install the Ollama Python library: + +```shell +pip install --upgrade ollama +``` + +Set your API key for the current terminal session: + + + + +```shell +export OLLAMA_API_KEY=your_api_key +``` + + + + +```powershell +$env:OLLAMA_API_KEY="your_api_key" +``` + + + + + + Environment variables set this way last only for the current terminal session. Use your operating system's secret manager for a persistent setup. + + +## 2. Pull and test the Cloud model + +Sign in to your Ollama account: + +```shell +ollama signin +``` + +Pull `gpt-oss:120b-cloud`: + +```shell +ollama pull gpt-oss:120b-cloud +``` + +This downloads the Cloud model configuration, not the 120B model weights. The model runs on Ollama's infrastructure when you use it. + +Send a test prompt to confirm that the model is ready: + +```shell +ollama run gpt-oss:120b-cloud "Reply with exactly: Cloud model ready" +``` + +You should receive: + +```text +Cloud model ready +``` + +The research agent will use this same model through the Ollama Python library. + +## 3. Create the agent + +Save the following as `research_agent.py`: + +```python +import os +import sys +from datetime import datetime +from pathlib import Path + +from ollama import Client, RequestError, ResponseError, web_fetch, web_search + + +# The ":cloud" suffix tells Ollama to run this model in Ollama Cloud +# The "120b" tells Ollama what quantization level to use +MODEL = "gpt-oss:120b-cloud" +MAX_TOOL_ROUNDS = 8 +MAX_SOURCE_CHARS = 12000 + +DEFAULT_QUESTION = ( + "What have four-day workweek pilots since 2022 reported about " + "employee wellbeing and business performance?" +) + +# These are the only tools the model is allowed to call +TOOLS = { + "web_search": web_search, + "web_fetch": web_fetch, +} + +SYSTEM_PROMPT = """You are a careful research agent. + +Research the user's question before answering. Search broadly, then fetch the +most useful pages. Prefer primary sources, original studies, official reports, +and sources that clearly explain their methods. +Only call web_fetch with an exact URL returned by web_search. Never guess or +construct a source URL. + +Your final answer must contain: +1. An executive summary +2. Key findings, including disagreements between sources +3. Limitations and missing evidence +4. Practical next steps +5. A Sources section with Markdown links + +Attach a source link to every important factual claim. Never invent a citation. +If the available evidence does not support a conclusion, say so explicitly. +""" + +FINAL_REPORT_PROMPT = """Using the research above, write the complete cited +report now. Return only the Markdown report and do not call more tools.""" + + +def run_tool(name: str, arguments: dict) -> str: + """Run a tool requested by the model and return its result as text.""" + tool = TOOLS.get(name) + if tool is None: + return f"Unknown tool: {name}" + + print(f"Tool: {name}({arguments})", flush=True) + + try: + result = tool(**arguments) + except ResponseError as error: + # A page may have moved or may reject automated access. Returning the + # error lets the model search for another source instead of crashing + message = ( + f"{name} failed with HTTP {error.status_code}: {error.error}. " + "Do not cite this result. Try another search result or URL." + ) + print(f"Tool error: {message}", flush=True) + return message + except RequestError as error: + message = ( + f"{name} could not reach the service: {error}. " + "Try the request again or use another source." + ) + print(f"Tool error: {message}", flush=True) + return message + + # Limit long pages so one source does not fill the model's context window + return str(result)[:MAX_SOURCE_CHARS] + + +def create_final_report(client: Client, messages: list) -> str: + """Ask the model for the final report, retrying once if it is empty.""" + final_messages = messages + [ + {"role": "user", "content": FINAL_REPORT_PROMPT} + ] + + for _ in range(2): + # Omitting tools prevents the model from doing more research here + response = client.chat( + model=MODEL, + messages=final_messages, + think=False, + ) + report = response.message.content or "" + if report.strip(): + return report + + # Keep the empty response in the conversation, then ask once more + final_messages += [ + response.message, + { + "role": "user", + "content": "Your response was empty. Write the Markdown report now.", + }, + ] + + raise RuntimeError("The Cloud model returned an empty report twice.") + + +def research(question: str) -> str: + """Research a question and return a non-empty Markdown report.""" + # The web search and fetch APIs use this key automatically + if not os.environ.get("OLLAMA_API_KEY"): + raise RuntimeError("Set OLLAMA_API_KEY before running the agent.") + + # Client() connects to the local Ollama app. Ollama routes the :cloud model + # to Ollama Cloud because you signed in during setup + client = Client() + + # messages stores the complete conversation, including tool results + messages = [ + {"role": "system", "content": SYSTEM_PROMPT}, + {"role": "user", "content": question}, + ] + + for _ in range(MAX_TOOL_ROUNDS): + response = client.chat( + model=MODEL, + messages=messages, + tools=list(TOOLS.values()), + think=True, + ) + messages.append(response.message) + + tool_calls = response.message.tool_calls or [] + if not tool_calls: + # The model may return the finished report during the tool loop + report = response.message.content or "" + if report.strip(): + return report + break + + # Run every requested tool and send each result back to the model + for call in tool_calls: + name = call.function.name + result = run_tool(name, call.function.arguments) + messages.append( + { + "role": "tool", + "tool_name": name, + "content": result, + } + ) + + # This also runs when the agent reaches MAX_TOOL_ROUNDS + return create_final_report(client, messages) + + +def save_report(report: str) -> None: + """Save the report in a reusable output directory beside this script.""" + output_dir = Path(__file__).resolve().parent / "output" + output_dir.mkdir(exist_ok=True) + + timestamp = datetime.now().strftime("%Y-%m-%d_%H-%M-%S") + output_path = output_dir / f"Research report {timestamp}.md" + output_path.write_text(report, encoding="utf-8") + + +if __name__ == "__main__": + # Text after the script name (research_agent.py) becomes the research question. If no + # text is provided, the tutorial's default question is used + question = " ".join(sys.argv[1:]) or DEFAULT_QUESTION + report = research(question) + + # Never print or save a blank report + if not report.strip(): + raise RuntimeError("The research agent returned an empty report.") + + print(report, flush=True) + save_report(report) +``` + +The model receives the functions in `TOOLS`, decides when to call them, and uses their results in later turns. When research ends, the script accepts a non-empty report or runs `create_final_report` without tools. + +Search results sometimes point to pages that have moved, reject automated access, or no longer exist. The error handlers return those failures to the model as tool results so it can search for another source instead of stopping the program. + +`MAX_TOOL_ROUNDS` prevents an open-ended research loop. `create_final_report` disables thinking output and retries once if the model returns empty content. The script raises an error instead of creating an empty file if both attempts are empty. + +## 4. Run the project + +Run the agent with the example research question: + +```shell +python research_agent.py +``` + +Or provide your own question: + +```shell +python research_agent.py "What evidence supports later high school start times?" +``` + +During the run, the script prints each tool call. A typical trace looks like this: + +```text +Tool: web_search({'query': 'four-day workweek pilot 2022 study results'}) +Tool: web_search({'query': 'four-day week trial company revenue retention report'}) +Tool: web_fetch({'url': 'https://example.org/report'}) +Tool error: web_fetch failed with HTTP 404: not found. Do not cite this result. Try another search result or URL. +``` + +Search queries, sources, and occasional fetch errors will vary between runs. That is expected: the model chooses its next action from the evidence it has already gathered. A failed fetch should be followed by another search or source selection rather than a Python traceback. + +## 5. Review the result + +The first run creates an `output` directory next to `research_agent.py`. Later runs reuse the same directory. Each report is saved as a timestamped Markdown file, for example: + +```text +output/Research report 2026-10-06_15-45-12.md +``` + +The complete Markdown report is printed to the terminal before it is saved. Empty output is treated as an error, so the script will not create a blank report file. + +Expect a Markdown report with this general shape in the `./output/` folder: + +```text +# Research report + +## Executive summary +A concise answer to the research question. + +## Key findings +Findings grouped by theme, with links attached to factual claims. + +## Limitations +Gaps in the available evidence, methodology concerns, and conflicting results. + +## Practical next steps +Actions or questions that follow from the evidence. + +## Sources +A list of the pages used in the report. +``` + +The first run should produce a useful draft, not an unquestionable final answer. Check that links open, quoted numbers match their sources, and the report distinguishes published evidence from the model's interpretation. + + + Web results can be incomplete, outdated, or wrong. Review the original sources before using the report for medical, legal, financial, employment, or other high-impact decisions. + + +## What happens at each stage + +| Stage | What the Cloud model does | What you should expect | +| --- | --- | --- | +| Plan | Breaks the question into searchable claims | Several queries covering different aspects of the topic | +| Search | Calls `web_search` and evaluates result snippets | A visible tool trace; some searches may be discarded | +| Read | Calls `web_fetch` for promising pages | More detailed evidence from a smaller set of sources | +| Compare | Looks for agreement, conflicts, and missing context | Findings that separate strong evidence from uncertainty | +| Synthesize | Writes the requested report | A readable report with citations, caveats, and next steps | + +## Improve the agent + +Try these changes after the basic project works: + +- Change `SYSTEM_PROMPT` to require a particular audience, length, or report format. +- Ask the agent to prefer sources from specific domains or a date range. +- Increase `MAX_TOOL_ROUNDS` for broader research, or decrease it for faster, more focused runs. +- Save the final string to a Markdown file for sharing. +- Add a human approval step before the agent fetches unfamiliar domains. + +See [Tool calling](/guide/capabilities/tool-calling) for more agent-loop patterns and [Web search](/guide/capabilities/web-search) for the complete search and fetch interfaces. diff --git a/docs/index.mdx b/docs/index.mdx index f9c9e2641..afb4e075e 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -6,7 +6,7 @@ description: Learn what Ollama can do, choose cloud or local models, and find th Build with open models in Ollama Cloud or on your own hardware. -Follow the [quickstart](/quickstart), then choose the environment that matches your needs. +Follow the [quickstart](/guide/quickstart), then choose the environment that matches your needs. ## Choose where models run @@ -24,7 +24,7 @@ Cloud and local models use the same Ollama tools and API shapes. The main differ ## What you can build -Ollama supports [streaming](/capabilities/streaming), [tool calling](/capabilities/tool-calling), [structured outputs](/capabilities/structured-outputs), [vision](/capabilities/vision), [embeddings](/capabilities/embeddings), [thinking](/capabilities/thinking), and [web search](/capabilities/web-search). +Ollama supports [streaming](/guide/capabilities/streaming), [tool calling](/guide/capabilities/tool-calling), [structured outputs](/guide/capabilities/structured-outputs), [vision](/guide/capabilities/vision), [embeddings](/guide/capabilities/embeddings), [thinking](/guide/capabilities/thinking), and [web search](/guide/capabilities/web-search). ## Next steps @@ -63,11 +63,11 @@ Connect Ollama to an app, or build with the API. Join the Ollama subreddit. - - Join the Ollama X (Twitter). + + Follow Ollama on X. - - Join the Ollama GitHub. + + Explore Ollama on GitHub. diff --git a/docs/integrations/claude-code.mdx b/docs/integrations/claude-code.mdx index 499b8c833..4da08b3c1 100644 --- a/docs/integrations/claude-code.mdx +++ b/docs/integrations/claude-code.mdx @@ -107,7 +107,7 @@ Choose a model with enough context for your repository. -For larger repositories, set the [context length](/context-length) to 64k or higher. +For larger repositories, set the [context length](/local/context-length) to 64k or higher. ## More features @@ -125,7 +125,7 @@ The `--yes` flag skips selectors, pulls the model when needed, and requires `--m Use Ollama's web search API from Claude Code. -See [Web search](/capabilities/web-search) for setup and usage. +See [Web search](/guide/capabilities/web-search) for setup and usage. ### Scheduled tasks with `/loop` diff --git a/docs/integrations/cline.mdx b/docs/integrations/cline.mdx index 371fc6288..a3a93f912 100644 --- a/docs/integrations/cline.mdx +++ b/docs/integrations/cline.mdx @@ -13,7 +13,7 @@ Install [Cline](https://docs.cline.bot/getting-started/installing-cline) in your 2. Select a model under `Model` or type one (e.g. `qwen3`) 3. Update the context window to at least 32K tokens under `Context Window` -Coding tools require a larger context window. It is recommended to use a context window of at least 32K tokens. See [Context length](/context-length) for more information. +Coding tools require a larger context window. It is recommended to use a context window of at least 32K tokens. See [Context length](/local/context-length) for more information.
Droid requires a larger context window. It is recommended to use a context window of at least 64k tokens. See [Context length](/context-length) for more information. +Droid requires a larger context window. It is recommended to use a context window of at least 64k tokens. See [Context length](/local/context-length) for more information. ## Usage with Ollama diff --git a/docs/integrations/openclaw.mdx b/docs/integrations/openclaw.mdx index ff5f91e26..bb891ea37 100644 --- a/docs/integrations/openclaw.mdx +++ b/docs/integrations/openclaw.mdx @@ -18,7 +18,7 @@ Ollama handles everything automatically: 4. **Onboarding** — Ollama configures the provider, installs the gateway daemon, sets your model as the primary, and enables OpenClaw's bundled Ollama web search 5. **Gateway** — Starts in the background and opens the OpenClaw TUI -OpenClaw requires a larger context window. It is recommended to use a context window of at least 64k tokens if using local models. See [Context length](/context-length) for more information. +OpenClaw requires a larger context window. It is recommended to use a context window of at least 64k tokens if using local models. See [Context length](/local/context-length) for more information. Previously known as Clawdbot. `ollama launch clawdbot` still works as an alias. diff --git a/docs/integrations/opencode.mdx b/docs/integrations/opencode.mdx index 12a9cb32e..71dca27eb 100644 --- a/docs/integrations/opencode.mdx +++ b/docs/integrations/opencode.mdx @@ -82,7 +82,7 @@ Choose a model with enough context for your repository. -OpenCode requires a context length of 64k or higher. See [Context length](/context-length) for more information. +OpenCode requires a context length of 64k or higher. See [Context length](/local/context-length) for more information. ## Manual setup diff --git a/docs/integrations/roo-code.mdx b/docs/integrations/roo-code.mdx index 61c91a717..c4184d3fc 100644 --- a/docs/integrations/roo-code.mdx +++ b/docs/integrations/roo-code.mdx @@ -15,7 +15,7 @@ Install [Roo Code](https://marketplace.visualstudio.com/items?itemName=RooVeteri 4. Enter a valid `Model ID` (for example `qwen3` or `qwen3-coder:480b-cloud`) 5. Adjust the `Context Window` to at least 32K tokens for coding tasks -Coding tools require a larger context window. It is recommended to use a context window of at least 32K tokens. See [Context length](/context-length) for more information. +Coding tools require a larger context window. It is recommended to use a context window of at least 32K tokens. See [Context length](/local/context-length) for more information. ## Connecting to ollama.com diff --git a/docs/integrations/vscode.mdx b/docs/integrations/vscode.mdx index 7d4ef52cf..488d20d66 100644 --- a/docs/integrations/vscode.mdx +++ b/docs/integrations/vscode.mdx @@ -44,7 +44,7 @@ Local models do not require sign-in. VS Code may show a model's maximum supported context length even when Ollama allocates a smaller context at runtime. -For local models, open Ollama **Settings**, set the context length to at least 64k, reload the VS Code window, and resend your prompt. See [Context length](/context-length) for more information. +For local models, open Ollama **Settings**, set the context length to at least 64k, reload the VS Code window, and resend your prompt. See [Context length](/local/context-length) for more information. ## Troubleshooting diff --git a/docs/cli.mdx b/docs/local/cli.mdx similarity index 100% rename from docs/cli.mdx rename to docs/local/cli.mdx diff --git a/docs/context-length.mdx b/docs/local/context-length.mdx similarity index 95% rename from docs/context-length.mdx rename to docs/local/context-length.mdx index abc2133b8..2d03c94f8 100644 --- a/docs/context-length.mdx +++ b/docs/local/context-length.mdx @@ -22,7 +22,7 @@ Cloud models are set to their maximum context length by default. ### App Change the slider in the Ollama app under settings to your desired context length. -![Context length in Ollama app](./images/ollama-settings.png) +![Context length in Ollama app](/images/ollama-settings.png) ### CLI If editing the context length for Ollama is not possible, the context length can also be updated when serving Ollama. diff --git a/docs/docker.mdx b/docs/local/docker.mdx similarity index 100% rename from docs/docker.mdx rename to docs/local/docker.mdx diff --git a/docs/faq.mdx b/docs/local/faq.mdx similarity index 99% rename from docs/faq.mdx rename to docs/local/faq.mdx index 92a7404da..452c21cc0 100644 --- a/docs/faq.mdx +++ b/docs/local/faq.mdx @@ -248,7 +248,7 @@ Refer to the section [above](#how-do-i-configure-ollama-server) for how to set e ## How can I use Ollama in Visual Studio Code? -Install the [Ollama extension](https://marketplace.visualstudio.com/items?itemName=Ollama.ollama) to use Ollama models in VS Code Chat. See the [VS Code integration guide](./integrations/vscode.mdx) for setup and troubleshooting. +Install the [Ollama extension](https://marketplace.visualstudio.com/items?itemName=Ollama.ollama) to use Ollama models in VS Code Chat. See the [VS Code integration guide](/integrations/vscode) for setup and troubleshooting. ## How do I use Ollama with GPU acceleration in Docker? diff --git a/docs/gpu.mdx b/docs/local/gpu.mdx similarity index 99% rename from docs/gpu.mdx rename to docs/local/gpu.mdx index e0e141442..97ecf3f66 100644 --- a/docs/gpu.mdx +++ b/docs/local/gpu.mdx @@ -35,7 +35,7 @@ Check your compute compatibility to see if your card is supported: | 5.0 | GeForce GTX | `GTX 750 Ti` `GTX 750` `NVS 810` | | | Quadro | `K2200` `K1200` `K620` `M1200` `M520` `M5000M` `M4000M` `M3000M` `M2000M` `M1000M` `K620M` `M600M` `M500M` | -For building locally to support older GPUs, see [development](./development.md). +For building locally to support older GPUs, see [development](/development). ### GPU Selection diff --git a/docs/import.mdx b/docs/local/import.mdx similarity index 100% rename from docs/import.mdx rename to docs/local/import.mdx diff --git a/docs/local.mdx b/docs/local/index.mdx similarity index 58% rename from docs/local.mdx rename to docs/local/index.mdx index dafc22b59..7cb107482 100644 --- a/docs/local.mdx +++ b/docs/local/index.mdx @@ -11,19 +11,19 @@ Run models on your own hardware with Ollama. Local inference keeps model executi Choose the installation guide for your environment. - + Install the Ollama app on Apple silicon or Intel hardware. - + Install the native Windows application. - + Install Ollama with the install script or a manual package. - + Run Ollama in a container with CPU or GPU acceleration. @@ -48,10 +48,10 @@ curl http://localhost:11434/api/chat -d '{ ## Configure your environment -- Use the [CLI reference](/cli) to run, download, copy, and remove models. -- Adjust the [context length](/context-length) for agents and other long-context workloads. -- Review [hardware support](/gpu) for GPU compatibility and acceleration. -- [Import a model](/import) or create a customized model with a [Modelfile](/modelfile). -- Use [local-only mode](/faq#how-do-i-disable-ollama-cloud-features) to disable Ollama Cloud features. +- Use the [CLI reference](/local/cli) to run, download, copy, and remove models. +- Adjust the [context length](/local/context-length) for agents and other long-context workloads. +- Review [hardware support](/local/gpu) for GPU compatibility and acceleration. +- [Import a model](/local/import) or create a customized model with a [Modelfile](/local/modelfile). +- Use [local-only mode](/local/faq#how-do-i-disable-ollama-cloud-features) to disable Ollama Cloud features. -For failures, start with [Troubleshooting](/troubleshooting). +For failures, start with [Troubleshooting](/local/troubleshooting). diff --git a/docs/linux.mdx b/docs/local/linux.mdx similarity index 100% rename from docs/linux.mdx rename to docs/local/linux.mdx diff --git a/docs/macos.mdx b/docs/local/macos.mdx similarity index 100% rename from docs/macos.mdx rename to docs/local/macos.mdx diff --git a/docs/modelfile.mdx b/docs/local/modelfile.mdx similarity index 100% rename from docs/modelfile.mdx rename to docs/local/modelfile.mdx diff --git a/docs/template.mdx b/docs/local/template.mdx similarity index 100% rename from docs/template.mdx rename to docs/local/template.mdx diff --git a/docs/troubleshooting.mdx b/docs/local/troubleshooting.mdx similarity index 100% rename from docs/troubleshooting.mdx rename to docs/local/troubleshooting.mdx diff --git a/docs/windows.mdx b/docs/local/windows.mdx similarity index 100% rename from docs/windows.mdx rename to docs/local/windows.mdx diff --git a/docs/sample-projects/research-brief-agent.mdx b/docs/sample-projects/research-brief-agent.mdx deleted file mode 100644 index e10839bf1..000000000 --- a/docs/sample-projects/research-brief-agent.mdx +++ /dev/null @@ -1,306 +0,0 @@ ---- -title: Build a research brief agent -sidebarTitle: Research brief agent -description: Build an Ollama Cloud agent that searches the web, reads primary sources, and produces a cited research brief. ---- - -Build an agent that researches a question and turns its findings into a cited decision brief. This is useful for market research, policy summaries, product comparisons, event planning, and other tasks where current sources matter. - -The project uses an Ollama Cloud model for reasoning and the Ollama web search and web fetch APIs for research. It runs entirely through Ollama Cloud, so you do not need a local model or GPU. - -## What you will build - -Given a question such as: - -> What have four-day workweek pilots since 2022 reported about employee wellbeing and business performance? - -the agent will: - -1. Turn the question into several focused searches. -2. Search the web and choose promising results. -3. Fetch source pages for more context. -4. Compare claims across sources. -5. Write a brief with links, caveats, and suggested follow-up questions. - -The example uses `gpt-oss:120b`, but you can choose another tool-capable model returned by the Cloud API. - -## Before you begin - -You need: - -- Python 3.10 or later -- An [Ollama account](https://ollama.com) -- An [Ollama API key](https://ollama.com/settings/keys) - -The API key gives the script access to both the Cloud model and the [web search tools](/capabilities/web-search). Treat it like a password and do not add it to source control. - -## 1. Set up the project - -Create a project directory and a Python virtual environment: - - - - -```shell -mkdir research-brief-agent -cd research-brief-agent -python3 -m venv .venv -source .venv/bin/activate -``` - - - - -```powershell -mkdir research-brief-agent -cd research-brief-agent -py -m venv .venv -.venv\Scripts\Activate.ps1 -``` - - - - -Install the Ollama Python library: - -```shell -pip install --upgrade ollama -``` - -Set your API key for the current terminal session: - - - - -```shell -export OLLAMA_API_KEY=your_api_key -``` - - - - -```powershell -$env:OLLAMA_API_KEY="your_api_key" -``` - - - - - - Environment variables set this way last only for the current terminal session. Use your operating system's secret manager for a persistent setup. - - -## 2. Check Cloud access - -List the models available to your account: - -```shell -curl https://ollama.com/api/tags \ - -H "Authorization: Bearer $OLLAMA_API_KEY" -``` - -Look for `gpt-oss:120b` in the response. If it is not available, choose another Cloud model that supports tool calling and set its name with `OLLAMA_MODEL`: - - - - -```shell -export OLLAMA_MODEL=your_model_name -``` - - - - -```powershell -$env:OLLAMA_MODEL="your_model_name" -``` - - - - -## 3. Create the agent - -Save the following as `research_agent.py`: - -```python -import os -import sys - -from ollama import Client, web_fetch, web_search - - -MODEL = os.getenv("OLLAMA_MODEL", "gpt-oss:120b") -MAX_TOOL_ROUNDS = 8 - -SYSTEM_PROMPT = """You are a careful research agent. - -Research the user's question before answering. Search broadly, then fetch the -most useful pages. Prefer primary sources, original studies, official reports, -and sources that clearly explain their methods. - -Your final answer must contain: -1. An executive summary -2. Key findings, including disagreements between sources -3. Limitations and missing evidence -4. Practical next steps -5. A Sources section with Markdown links - -Attach a source link to every important factual claim. Never invent a citation. -If the available evidence does not support a conclusion, say so explicitly. -""" - - -def run_tool(name: str, arguments: dict) -> str: - """Run one tool selected by the model and return text for the next turn.""" - tools = { - "web_search": web_search, - "web_fetch": web_fetch, - } - - tool = tools.get(name) - if tool is None: - return f"Unknown tool: {name}" - - print(f"Tool: {name}({arguments})") - result = tool(**arguments) - - # Large pages can crowd useful evidence out of the model's context. - return str(result)[:12000] - - -def research(question: str) -> str: - api_key = os.environ.get("OLLAMA_API_KEY") - if not api_key: - raise RuntimeError("Set OLLAMA_API_KEY before running the agent.") - - client = Client( - host="https://ollama.com", - headers={"Authorization": f"Bearer {api_key}"}, - ) - - messages = [ - {"role": "system", "content": SYSTEM_PROMPT}, - {"role": "user", "content": question}, - ] - - for _ in range(MAX_TOOL_ROUNDS): - response = client.chat( - model=MODEL, - messages=messages, - tools=[web_search, web_fetch], - think=True, - ) - messages.append(response.message) - - if not response.message.tool_calls: - return response.message.content - - for call in response.message.tool_calls: - name = call.function.name - result = run_tool(name, call.function.arguments) - messages.append( - { - "role": "tool", - "tool_name": name, - "content": result, - } - ) - - # Force a final report if the model uses the full research budget. - messages.append( - { - "role": "user", - "content": "Stop researching and write the final cited brief now.", - } - ) - response = client.chat(model=MODEL, messages=messages, think=True) - return response.message.content - - -if __name__ == "__main__": - default_question = ( - "What have four-day workweek pilots since 2022 reported about " - "employee wellbeing and business performance?" - ) - question = " ".join(sys.argv[1:]) or default_question - print(research(question)) -``` - -The model receives two tools as Python functions. Ollama converts those functions into tool definitions, the Cloud model decides when and how to call them, and the script returns each tool result to the model. The loop ends when the model produces a response without another tool call. - -`MAX_TOOL_ROUNDS` prevents an open-ended research loop. The final request removes the tools and asks for a report if the agent uses its entire tool budget. - -## 4. Run the project - -Run the agent with the example research question: - -```shell -python research_agent.py -``` - -Or provide your own question: - -```shell -python research_agent.py "What evidence supports later high school start times?" -``` - -During the run, the script prints each tool call. A typical trace looks like this: - -```text -Tool: web_search({'query': 'four-day workweek pilot 2022 study results'}) -Tool: web_search({'query': 'four-day week trial company revenue retention report'}) -Tool: web_fetch({'url': 'https://example.org/report'}) -``` - -Search queries and sources will vary between runs. That is expected: the model chooses its next action from the evidence it has already gathered. - -## 5. Review the result - -Expect a Markdown report with this general shape: - -```text -# Research brief - -## Executive summary -A concise answer to the research question. - -## Key findings -Findings grouped by theme, with links attached to factual claims. - -## Limitations -Gaps in the available evidence, methodology concerns, and conflicting results. - -## Practical next steps -Actions or questions that follow from the evidence. - -## Sources -A list of the pages used in the report. -``` - -The first run should produce a useful draft, not an unquestionable final answer. Check that links open, quoted numbers match their sources, and the report distinguishes published evidence from the model's interpretation. - - - Web results can be incomplete, outdated, or wrong. Review the original sources before using the brief for medical, legal, financial, employment, or other high-impact decisions. - - -## What happens at each stage - -| Stage | What the Cloud model does | What you should expect | -| --- | --- | --- | -| Plan | Breaks the question into searchable claims | Several queries covering different aspects of the topic | -| Search | Calls `web_search` and evaluates result snippets | A visible tool trace; some searches may be discarded | -| Read | Calls `web_fetch` for promising pages | More detailed evidence from a smaller set of sources | -| Compare | Looks for agreement, conflicts, and missing context | Findings that separate strong evidence from uncertainty | -| Synthesize | Writes the requested report | A readable brief with citations, caveats, and next steps | - -## Improve the agent - -Try these changes after the basic project works: - -- Change `SYSTEM_PROMPT` to require a particular audience, length, or report format. -- Ask the agent to prefer sources from specific domains or a date range. -- Increase `MAX_TOOL_ROUNDS` for broader research, or decrease it for faster, more focused runs. -- Save the final string to a Markdown file for sharing. -- Add a human approval step before the agent fetches unfamiliar domains. - -See [Tool calling](/capabilities/tool-calling) for more agent-loop patterns and [Web search](/capabilities/web-search) for the complete search and fetch interfaces. From 1f51984dc312a1711e543c54d6b5da5ec4605b35 Mon Sep 17 00:00:00 2001 From: Anna Rahn Date: Wed, 7 Oct 2026 10:00:44 -0700 Subject: [PATCH 3/8] keeping old urls, updating model retirement page --- docs/README.md | 18 +-- docs/api.md | 10 +- docs/api/authentication.mdx | 2 +- docs/api/introduction.mdx | 2 +- docs/{guide => }/capabilities/decision.mdx | 2 +- docs/{guide => }/capabilities/embeddings.mdx | 0 docs/{guide => }/capabilities/streaming.mdx | 0 .../capabilities/structured-outputs.mdx | 0 docs/{guide => }/capabilities/thinking.mdx | 0 .../{guide => }/capabilities/tool-calling.mdx | 0 docs/{guide => }/capabilities/vision.mdx | 0 docs/{guide => }/capabilities/web-search.mdx | 0 docs/{local => }/cli.mdx | 0 docs/{cloud/index.mdx => cloud.mdx} | 2 +- docs/cloud/faq.mdx | 6 +- docs/cloud/model-lifecycle.mdx | 20 ++- docs/{local => }/context-length.mdx | 0 docs/{local => }/docker.mdx | 0 docs/docs.json | 130 +++++++++--------- docs/{local => }/faq.mdx | 0 docs/{local => }/gpu.mdx | 0 .../sample-projects/research-report-agent.mdx | 4 +- docs/{local => }/import.mdx | 0 docs/index.mdx | 6 +- docs/integrations/claude-code.mdx | 6 +- docs/integrations/claude-desktop.mdx | 2 +- docs/integrations/cline.mdx | 2 +- docs/integrations/copilot-cli.mdx | 2 +- docs/integrations/droid.mdx | 2 +- docs/integrations/openclaw.mdx | 2 +- docs/integrations/opencode.mdx | 2 +- docs/integrations/roo-code.mdx | 2 +- docs/integrations/vscode.mdx | 2 +- docs/{local => }/linux.mdx | 0 docs/local/index.mdx | 20 +-- docs/{local => }/macos.mdx | 0 docs/{local => }/modelfile.mdx | 0 docs/{guide => }/quickstart.mdx | 2 +- docs/{local => }/template.mdx | 0 docs/{local => }/troubleshooting.mdx | 0 docs/{local => }/windows.mdx | 0 41 files changed, 129 insertions(+), 117 deletions(-) rename docs/{guide => }/capabilities/decision.mdx (97%) rename docs/{guide => }/capabilities/embeddings.mdx (100%) rename docs/{guide => }/capabilities/streaming.mdx (100%) rename docs/{guide => }/capabilities/structured-outputs.mdx (100%) rename docs/{guide => }/capabilities/thinking.mdx (100%) rename docs/{guide => }/capabilities/tool-calling.mdx (100%) rename docs/{guide => }/capabilities/vision.mdx (100%) rename docs/{guide => }/capabilities/web-search.mdx (100%) rename docs/{local => }/cli.mdx (100%) rename docs/{cloud/index.mdx => cloud.mdx} (93%) rename docs/{local => }/context-length.mdx (100%) rename docs/{local => }/docker.mdx (100%) rename docs/{local => }/faq.mdx (100%) rename docs/{local => }/gpu.mdx (100%) rename docs/{local => }/import.mdx (100%) rename docs/{local => }/linux.mdx (100%) rename docs/{local => }/macos.mdx (100%) rename docs/{local => }/modelfile.mdx (100%) rename docs/{guide => }/quickstart.mdx (97%) rename docs/{local => }/template.mdx (100%) rename docs/{local => }/troubleshooting.mdx (100%) rename docs/{local => }/windows.mdx (100%) diff --git a/docs/README.md b/docs/README.md index c2caa9e51..f11addb3f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,29 +2,29 @@ ### Getting started -* [Quickstart](https://docs.ollama.com/guide/quickstart) +* [Quickstart](https://docs.ollama.com/quickstart) * [Ollama Cloud](https://docs.ollama.com/cloud) * [Run Ollama locally](https://docs.ollama.com/local) * [Examples](./examples.md) ### Local -* [macOS](https://docs.ollama.com/local/macos) -* [Linux](https://docs.ollama.com/local/linux) -* [Windows](https://docs.ollama.com/local/windows) -* [Docker](https://docs.ollama.com/local/docker) -* [Importing models](https://docs.ollama.com/local/import) +* [macOS](https://docs.ollama.com/macos) +* [Linux](https://docs.ollama.com/linux) +* [Windows](https://docs.ollama.com/windows) +* [Docker](https://docs.ollama.com/docker) +* [Importing models](https://docs.ollama.com/import) ### Reference * [API Reference](https://docs.ollama.com/api) -* [Modelfile Reference](https://docs.ollama.com/local/modelfile) +* [Modelfile Reference](https://docs.ollama.com/modelfile) * [OpenAI Compatibility](https://docs.ollama.com/api/openai-compatibility) * [Anthropic Compatibility](./api/anthropic-compatibility.mdx) ### Resources -* [Troubleshooting Guide](https://docs.ollama.com/local/troubleshooting) -* [Local FAQ](https://docs.ollama.com/local/faq) +* [Troubleshooting Guide](https://docs.ollama.com/troubleshooting) +* [Local FAQ](https://docs.ollama.com/faq) * [Cloud FAQ](https://docs.ollama.com/cloud/faq) * [Development guide](./development.md) diff --git a/docs/api.md b/docs/api.md index 7617a1bfc..595f7857e 100644 --- a/docs/api.md +++ b/docs/api.md @@ -50,7 +50,7 @@ Generate a response for a given prompt with a provided model. This is a streamin Advanced parameters (optional): - `format`: the format to return a response in. Format can be `json` or a JSON schema -- `options`: additional model parameters listed in the documentation for the [Modelfile](./local/modelfile.mdx#valid-parameters-and-values) such as `temperature` +- `options`: additional model parameters listed in the documentation for the [Modelfile](./modelfile.mdx#valid-parameters-and-values) such as `temperature` - `system`: system message to (overrides what is defined in the `Modelfile`) - `template`: the prompt template to use (overrides what is defined in the `Modelfile`) - `stream`: if `false` the response will be returned as a single response object, rather than a stream of objects @@ -510,7 +510,7 @@ The `message` object has the following fields: Advanced parameters (optional): - `format`: the format to return a response in. Format can be `json` or a JSON schema. -- `options`: additional model parameters listed in the documentation for the [Modelfile](./local/modelfile.mdx#valid-parameters-and-values) such as `temperature` +- `options`: additional model parameters listed in the documentation for the [Modelfile](./modelfile.mdx#valid-parameters-and-values) such as `temperature` - `stream`: if `false` the response will be returned as a single response object, rather than a stream of objects - `keep_alive`: controls how long the model will stay loaded into memory following the request (default: `5m`) @@ -1195,7 +1195,7 @@ If you are creating a model from a safetensors directory or from GGUF files, you - `parser`: (optional) the name of the parser for the model - `license`: (optional) a string or list of strings containing the license or licenses for the model - `system`: (optional) a string containing the system prompt for the model -- `parameters`: (optional) a dictionary of parameters for the model (see [Modelfile](./local/modelfile.mdx#valid-parameters-and-values) for a list of parameters) +- `parameters`: (optional) a dictionary of parameters for the model (see [Modelfile](./modelfile.mdx#valid-parameters-and-values) for a list of parameters) - `messages`: (optional) a list of message objects used to create a conversation - `capabilities`: (optional) capabilities to add without removing inherited or inferred capabilities, such as `["decision"]` for compatible decision models - `stream`: (optional) if `false` the response will be returned as a single response object, rather than a stream of objects @@ -1679,7 +1679,7 @@ Generate embeddings from a model Advanced parameters: - `truncate`: truncates the end of each input to fit within context length. Returns error if `false` and context length is exceeded. Defaults to `true` -- `options`: additional model parameters listed in the documentation for the [Modelfile](./local/modelfile.mdx#valid-parameters-and-values) such as `temperature` +- `options`: additional model parameters listed in the documentation for the [Modelfile](./modelfile.mdx#valid-parameters-and-values) such as `temperature` - `keep_alive`: controls how long the model will stay loaded into memory following the request (default: `5m`) - `dimensions`: number of dimensions for the embedding @@ -1820,7 +1820,7 @@ Generate embeddings from a model Advanced parameters: -- `options`: additional model parameters listed in the documentation for the [Modelfile](./local/modelfile.mdx#valid-parameters-and-values) such as `temperature` +- `options`: additional model parameters listed in the documentation for the [Modelfile](./modelfile.mdx#valid-parameters-and-values) such as `temperature` - `keep_alive`: controls how long the model will stay loaded into memory following the request (default: `5m`) ### Examples diff --git a/docs/api/authentication.mdx b/docs/api/authentication.mdx index 3c5769130..ad8417d4e 100644 --- a/docs/api/authentication.mdx +++ b/docs/api/authentication.mdx @@ -31,7 +31,7 @@ curl https://ollama.com/api/chat \ API keys do not expire. Revoke a key in [API keys settings](https://ollama.com/settings/keys). -Keep keys outside browser code and source control. See the [API quickstart](/guide/quickstart#build-an-application) for shell setup and compatibility examples. +Keep keys outside browser code and source control. See the [API quickstart](/quickstart#build-an-application) for shell setup and compatibility examples. ## Signing in diff --git a/docs/api/introduction.mdx b/docs/api/introduction.mdx index 9ab8ec7e8..80ba0b90a 100644 --- a/docs/api/introduction.mdx +++ b/docs/api/introduction.mdx @@ -29,7 +29,7 @@ The Anthropic client appends `/v1/messages` to its base URL. Cloud requests need an API key. Local requests do not. To use cloud models through your local server, [sign in to Ollama](/api/authentication#signing-in). -Creating or deleting models requires a local Ollama server. [System One](/guide/capabilities/decision) also requires a local server and is not yet available on Ollama Cloud. For supported API features, see [OpenAI compatibility](/api/openai-compatibility) and [Anthropic compatibility](/api/anthropic-compatibility). +Creating or deleting models requires a local Ollama server. [System One](/capabilities/decision) also requires a local server and is not yet available on Ollama Cloud. For supported API features, see [OpenAI compatibility](/api/openai-compatibility) and [Anthropic compatibility](/api/anthropic-compatibility). ## Ollama API example diff --git a/docs/guide/capabilities/decision.mdx b/docs/capabilities/decision.mdx similarity index 97% rename from docs/guide/capabilities/decision.mdx rename to docs/capabilities/decision.mdx index 5bb16b5c9..264092e9f 100644 --- a/docs/guide/capabilities/decision.mdx +++ b/docs/capabilities/decision.mdx @@ -13,7 +13,7 @@ See the [full list of decision models](https://ollama.com/search?c=decision). ## Setup -Start [Ollama](/guide/quickstart) v0.35.0 or later, then download [Nimble](https://ollama.com/library/nimble): +Start [Ollama](/quickstart) v0.35.0 or later, then download [Nimble](https://ollama.com/library/nimble): ```shell setup.sh ollama pull nimble diff --git a/docs/guide/capabilities/embeddings.mdx b/docs/capabilities/embeddings.mdx similarity index 100% rename from docs/guide/capabilities/embeddings.mdx rename to docs/capabilities/embeddings.mdx diff --git a/docs/guide/capabilities/streaming.mdx b/docs/capabilities/streaming.mdx similarity index 100% rename from docs/guide/capabilities/streaming.mdx rename to docs/capabilities/streaming.mdx diff --git a/docs/guide/capabilities/structured-outputs.mdx b/docs/capabilities/structured-outputs.mdx similarity index 100% rename from docs/guide/capabilities/structured-outputs.mdx rename to docs/capabilities/structured-outputs.mdx diff --git a/docs/guide/capabilities/thinking.mdx b/docs/capabilities/thinking.mdx similarity index 100% rename from docs/guide/capabilities/thinking.mdx rename to docs/capabilities/thinking.mdx diff --git a/docs/guide/capabilities/tool-calling.mdx b/docs/capabilities/tool-calling.mdx similarity index 100% rename from docs/guide/capabilities/tool-calling.mdx rename to docs/capabilities/tool-calling.mdx diff --git a/docs/guide/capabilities/vision.mdx b/docs/capabilities/vision.mdx similarity index 100% rename from docs/guide/capabilities/vision.mdx rename to docs/capabilities/vision.mdx diff --git a/docs/guide/capabilities/web-search.mdx b/docs/capabilities/web-search.mdx similarity index 100% rename from docs/guide/capabilities/web-search.mdx rename to docs/capabilities/web-search.mdx diff --git a/docs/local/cli.mdx b/docs/cli.mdx similarity index 100% rename from docs/local/cli.mdx rename to docs/cli.mdx diff --git a/docs/cloud/index.mdx b/docs/cloud.mdx similarity index 93% rename from docs/cloud/index.mdx rename to docs/cloud.mdx index 0748a1054..7f8d24e00 100644 --- a/docs/cloud/index.mdx +++ b/docs/cloud.mdx @@ -30,7 +30,7 @@ Follow the [Cloud API guide](/cloud/api) to call `https://ollama.com/api` direct ## Local only -Use [Local](/local) when you want inference to run on your own hardware. Ollama can also run in [local-only mode](/local/faq#how-do-i-disable-ollama-cloud-features) with Cloud features disabled. +Use [Local](/local) when you want inference to run on your own hardware. Ollama can also run in [local-only mode](/faq#how-do-i-disable-ollama-cloud-features) with Cloud features disabled. ## Retirements diff --git a/docs/cloud/faq.mdx b/docs/cloud/faq.mdx index 41025e415..e5b2a1a61 100644 --- a/docs/cloud/faq.mdx +++ b/docs/cloud/faq.mdx @@ -4,7 +4,7 @@ sidebarTitle: FAQ description: Frequently asked questions about Ollama Cloud accounts, authentication, privacy, and requests. --- -For questions about installation, hardware, and the local Ollama server, see the [Local FAQ](/local/faq). +For questions about installation, hardware, and the local Ollama server, see the [Local FAQ](/faq). ## Does Ollama send my prompts and answers back to ollama.com? @@ -12,7 +12,7 @@ Ollama runs locally. We don't see your prompts or data when you run local models When you use Cloud models, Ollama processes your prompts and responses to provide the service but does not store or log that content and never trains on it. Ollama collects basic account information and limited usage metadata that does not include prompt or response content. Ollama does not sell your data, and you can delete your account at any time. -To prevent a local Ollama installation from using Cloud models and web search, enable [local-only mode](/local/faq#how-do-i-disable-ollama-cloud-features). +To prevent a local Ollama installation from using Cloud models and web search, enable [local-only mode](/faq#how-do-i-disable-ollama-cloud-features). ## How do I manage the maximum number of requests the Ollama server can queue? @@ -24,7 +24,7 @@ Set `OLLAMA_MAX_QUEUE` before starting the local server to change the maximum nu OLLAMA_MAX_QUEUE=1024 ollama serve ``` -See [How do I configure Ollama server?](/local/faq#how-do-i-configure-ollama-server) for operating-system-specific instructions for setting environment variables. +See [How do I configure Ollama server?](/faq#how-do-i-configure-ollama-server) for operating-system-specific instructions for setting environment variables. ## What is the difference between an API key and my Ollama Public Key? diff --git a/docs/cloud/model-lifecycle.mdx b/docs/cloud/model-lifecycle.mdx index a54865a56..3170b847f 100644 --- a/docs/cloud/model-lifecycle.mdx +++ b/docs/cloud/model-lifecycle.mdx @@ -9,14 +9,26 @@ Impacted users are notified before a model is retired. Cloud model retirement do ## Upcoming retirements -| Retirement date | Model | Recommended alternative | -| --- | --- | --- | -| July 31, 2026 | `minimax-m2.5` | `minimax-m2.7` | -| July 31, 2026 | `kimi-k2.5` | `kimi-k2.6` | +No Cloud model retirements are currently scheduled. ## Past retirements + + | Model | Recommended alternative | + | --- | --- | + | `qwen3.5:397b` | `glm-5.3` | + | `glm-5.1` | `glm-5.2` | + | `deepseek-v4-flash:0731` | `deepseek-v4.1-flash` | + + + + | Model | Recommended alternative | + | --- | --- | + | `minimax-m2.5` | `minimax-m2.7` | + | `kimi-k2.5` | `kimi-k2.6` | + + | Model | Recommended alternative | | --- | --- | diff --git a/docs/local/context-length.mdx b/docs/context-length.mdx similarity index 100% rename from docs/local/context-length.mdx rename to docs/context-length.mdx diff --git a/docs/local/docker.mdx b/docs/docker.mdx similarity index 100% rename from docs/local/docker.mdx rename to docs/docker.mdx diff --git a/docs/docs.json b/docs/docs.json index d2aac09fb..39e2217fa 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -70,7 +70,7 @@ }, { "source": "/gpu.mdx", - "destination": "/local/gpu" + "destination": "/gpu" }, { "source": "/integrations/vscode.mdx", @@ -78,7 +78,7 @@ }, { "source": "/troubleshooting.mdx", - "destination": "/local/troubleshooting" + "destination": "/troubleshooting" }, { "source": "/openai", @@ -109,40 +109,40 @@ "destination": "/integrations/pool" }, { - "source": "/quickstart", - "destination": "/guide/quickstart" + "source": "/guide/quickstart", + "destination": "/quickstart" }, { - "source": "/capabilities/streaming", - "destination": "/guide/capabilities/streaming" + "source": "/guide/capabilities/streaming", + "destination": "/capabilities/streaming" }, { - "source": "/capabilities/thinking", - "destination": "/guide/capabilities/thinking" + "source": "/guide/capabilities/thinking", + "destination": "/capabilities/thinking" }, { - "source": "/capabilities/structured-outputs", - "destination": "/guide/capabilities/structured-outputs" + "source": "/guide/capabilities/structured-outputs", + "destination": "/capabilities/structured-outputs" }, { - "source": "/capabilities/decision", - "destination": "/guide/capabilities/decision" + "source": "/guide/capabilities/decision", + "destination": "/capabilities/decision" }, { - "source": "/capabilities/vision", - "destination": "/guide/capabilities/vision" + "source": "/guide/capabilities/vision", + "destination": "/capabilities/vision" }, { - "source": "/capabilities/embeddings", - "destination": "/guide/capabilities/embeddings" + "source": "/guide/capabilities/embeddings", + "destination": "/capabilities/embeddings" }, { - "source": "/capabilities/tool-calling", - "destination": "/guide/capabilities/tool-calling" + "source": "/guide/capabilities/tool-calling", + "destination": "/capabilities/tool-calling" }, { - "source": "/capabilities/web-search", - "destination": "/guide/capabilities/web-search" + "source": "/guide/capabilities/web-search", + "destination": "/capabilities/web-search" }, { "source": "/sample-projects/research-brief-agent", @@ -153,52 +153,52 @@ "destination": "/guide/sample-projects/research-report-agent" }, { - "source": "/cli", - "destination": "/local/cli" + "source": "/local/cli", + "destination": "/cli" }, { - "source": "/context-length", - "destination": "/local/context-length" + "source": "/local/context-length", + "destination": "/context-length" }, { - "source": "/macos", - "destination": "/local/macos" + "source": "/local/macos", + "destination": "/macos" }, { - "source": "/linux", - "destination": "/local/linux" + "source": "/local/linux", + "destination": "/linux" }, { - "source": "/windows", - "destination": "/local/windows" + "source": "/local/windows", + "destination": "/windows" }, { - "source": "/docker", - "destination": "/local/docker" + "source": "/local/docker", + "destination": "/docker" }, { - "source": "/import", - "destination": "/local/import" + "source": "/local/import", + "destination": "/import" }, { - "source": "/modelfile", - "destination": "/local/modelfile" + "source": "/local/modelfile", + "destination": "/modelfile" }, { - "source": "/gpu", - "destination": "/local/gpu" + "source": "/local/gpu", + "destination": "/gpu" }, { - "source": "/troubleshooting", - "destination": "/local/troubleshooting" + "source": "/local/troubleshooting", + "destination": "/troubleshooting" }, { - "source": "/faq", - "destination": "/local/faq" + "source": "/local/faq", + "destination": "/faq" }, { - "source": "/template", - "destination": "/local/template" + "source": "/local/template", + "destination": "/template" } ], "navigation": { @@ -210,20 +210,20 @@ "group": "Get started", "pages": [ "index", - "/guide/quickstart" + "quickstart" ] }, { "group": "Capabilities", "pages": [ - "/guide/capabilities/streaming", - "/guide/capabilities/thinking", - "/guide/capabilities/structured-outputs", - "/guide/capabilities/decision", - "/guide/capabilities/vision", - "/guide/capabilities/embeddings", - "/guide/capabilities/tool-calling", - "/guide/capabilities/web-search" + "/capabilities/streaming", + "/capabilities/thinking", + "/capabilities/structured-outputs", + "/capabilities/decision", + "/capabilities/vision", + "/capabilities/embeddings", + "/capabilities/tool-calling", + "/capabilities/web-search" ] }, { @@ -241,32 +241,32 @@ "group": "Get started", "pages": [ "/local/index", - "/local/macos", - "/local/linux", - "/local/windows", - "/local/docker" + "/macos", + "/linux", + "/windows", + "/docker" ] }, { "group": "Run and configure", "pages": [ - "/local/cli", - "/local/context-length" + "/cli", + "/context-length" ] }, { "group": "Customize models", "pages": [ - "/local/import", - "/local/modelfile" + "/import", + "/modelfile" ] }, { "group": "Hardware and support", "pages": [ - "/local/gpu", - "/local/troubleshooting", - "/local/faq" + "/gpu", + "/troubleshooting", + "/faq" ] } ] @@ -277,7 +277,7 @@ { "group": "Get started", "pages": [ - "/cloud/index", + "/cloud", "/cloud/models", "/cloud/api" ] diff --git a/docs/local/faq.mdx b/docs/faq.mdx similarity index 100% rename from docs/local/faq.mdx rename to docs/faq.mdx diff --git a/docs/local/gpu.mdx b/docs/gpu.mdx similarity index 100% rename from docs/local/gpu.mdx rename to docs/gpu.mdx diff --git a/docs/guide/sample-projects/research-report-agent.mdx b/docs/guide/sample-projects/research-report-agent.mdx index 7a796f0a8..c399b969c 100644 --- a/docs/guide/sample-projects/research-report-agent.mdx +++ b/docs/guide/sample-projects/research-report-agent.mdx @@ -33,7 +33,7 @@ You need: - An [Ollama account](https://ollama.com) - An [Ollama API key](https://ollama.com/settings/keys) -Signing in to Ollama gives your local installation access to the Cloud model. The API key gives the script access to the [web search tools](/guide/capabilities/web-search). Treat the API key like a password and do not add it to source control. +Signing in to Ollama gives your local installation access to the Cloud model. The API key gives the script access to the [web search tools](/capabilities/web-search). Treat the API key like a password and do not add it to source control. ## 1. Set up the project @@ -395,4 +395,4 @@ Try these changes after the basic project works: - Save the final string to a Markdown file for sharing. - Add a human approval step before the agent fetches unfamiliar domains. -See [Tool calling](/guide/capabilities/tool-calling) for more agent-loop patterns and [Web search](/guide/capabilities/web-search) for the complete search and fetch interfaces. +See [Tool calling](/capabilities/tool-calling) for more agent-loop patterns and [Web search](/capabilities/web-search) for the complete search and fetch interfaces. diff --git a/docs/local/import.mdx b/docs/import.mdx similarity index 100% rename from docs/local/import.mdx rename to docs/import.mdx diff --git a/docs/index.mdx b/docs/index.mdx index 228472536..c631bcfe1 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -7,10 +7,10 @@ description: Learn what Ollama can do, choose cloud or local models, and find th Use open models in your desktop apps and coding agents, or build them into your application. - + Connect Claude or ChatGPT on your desktop, or launch a coding agent from your terminal. - + Call cloud models with Ollama, OpenAI, or Anthropic APIs. @@ -33,7 +33,7 @@ Browse the [model library](https://ollama.com/search) for coding, vision, embedd ## What you can build -Ollama supports [streaming](/guide/capabilities/streaming), [tool calling](/guide/capabilities/tool-calling), [structured outputs](/guide/capabilities/structured-outputs), [decision models](/guide/capabilities/decision), [vision](/guide/capabilities/vision), [embeddings](/guide/capabilities/embeddings), [thinking](/guide/capabilities/thinking), and [web search](/guide/capabilities/web-search). +Ollama supports [streaming](/capabilities/streaming), [tool calling](/capabilities/tool-calling), [structured outputs](/capabilities/structured-outputs), [decision models](/capabilities/decision), [vision](/capabilities/vision), [embeddings](/capabilities/embeddings), [thinking](/capabilities/thinking), and [web search](/capabilities/web-search). ## Documentation diff --git a/docs/integrations/claude-code.mdx b/docs/integrations/claude-code.mdx index ebec14975..b27b8834f 100644 --- a/docs/integrations/claude-code.mdx +++ b/docs/integrations/claude-code.mdx @@ -107,7 +107,7 @@ Choose a model with enough context for your repository. -For larger repositories, set the [context length](/local/context-length) to 64k or higher. +For larger repositories, set the [context length](/context-length) to 64k or higher. ## More features @@ -125,7 +125,7 @@ The `--yes` flag skips selectors, pulls the model when needed, and requires `--m Use Ollama's web search API from Claude Code. -See [Web search](/guide/capabilities/web-search) for setup and usage. +See [Web search](/capabilities/web-search) for setup and usage. ### Scheduled tasks with `/loop` @@ -157,7 +157,7 @@ See the [plugin README](https://github.com/anthropics/claude-plugins-official/tr ## Connect directly to Ollama Cloud -Install Claude Code, then set your [API key](/guide/quickstart#build-an-application) in `OLLAMA_API_KEY`. No Ollama installation required. +Install Claude Code, then set your [API key](/quickstart#build-an-application) in `OLLAMA_API_KEY`. No Ollama installation required. In Bash or Zsh, run: diff --git a/docs/integrations/claude-desktop.mdx b/docs/integrations/claude-desktop.mdx index 9c24e6911..258ad5f13 100644 --- a/docs/integrations/claude-desktop.mdx +++ b/docs/integrations/claude-desktop.mdx @@ -7,7 +7,7 @@ description: Use Ollama models in Claude on macOS. ## Prerequisites - [Ollama](https://ollama.com/download/). Windows support coming soon. -- To use a local model, [download it](/guide/quickstart#run-a-model-locally) before setup. +- To use a local model, [download it](/quickstart#run-a-model-locally) before setup. - To use a cloud model, sign in to Ollama and enable cloud models. Some models require a [paid plan](https://ollama.com/pricing). If Claude is not installed, Ollama offers to download it during setup. diff --git a/docs/integrations/cline.mdx b/docs/integrations/cline.mdx index 3cd6663bb..075f0a1eb 100644 --- a/docs/integrations/cline.mdx +++ b/docs/integrations/cline.mdx @@ -13,7 +13,7 @@ Install [Cline](https://docs.cline.bot/getting-started/installing-cline) in your 2. Select a model under `Model` or type one (e.g. `qwen3`) 3. Update the context window to at least 32K tokens under `Context Window` -Use a [context window](/local/context-length) of at least 32K tokens for coding. +Use a [context window](/context-length) of at least 32K tokens for coding.
Droid requires a larger context window. It is recommended to use a context window of at least 64k tokens. See [Context length](/local/context-length) for more information. +Droid requires a larger context window. It is recommended to use a context window of at least 64k tokens. See [Context length](/context-length) for more information. ## Usage with Ollama diff --git a/docs/integrations/openclaw.mdx b/docs/integrations/openclaw.mdx index bb891ea37..ff5f91e26 100644 --- a/docs/integrations/openclaw.mdx +++ b/docs/integrations/openclaw.mdx @@ -18,7 +18,7 @@ Ollama handles everything automatically: 4. **Onboarding** — Ollama configures the provider, installs the gateway daemon, sets your model as the primary, and enables OpenClaw's bundled Ollama web search 5. **Gateway** — Starts in the background and opens the OpenClaw TUI -OpenClaw requires a larger context window. It is recommended to use a context window of at least 64k tokens if using local models. See [Context length](/local/context-length) for more information. +OpenClaw requires a larger context window. It is recommended to use a context window of at least 64k tokens if using local models. See [Context length](/context-length) for more information. Previously known as Clawdbot. `ollama launch clawdbot` still works as an alias. diff --git a/docs/integrations/opencode.mdx b/docs/integrations/opencode.mdx index 71dca27eb..12a9cb32e 100644 --- a/docs/integrations/opencode.mdx +++ b/docs/integrations/opencode.mdx @@ -82,7 +82,7 @@ Choose a model with enough context for your repository. -OpenCode requires a context length of 64k or higher. See [Context length](/local/context-length) for more information. +OpenCode requires a context length of 64k or higher. See [Context length](/context-length) for more information. ## Manual setup diff --git a/docs/integrations/roo-code.mdx b/docs/integrations/roo-code.mdx index c4184d3fc..61c91a717 100644 --- a/docs/integrations/roo-code.mdx +++ b/docs/integrations/roo-code.mdx @@ -15,7 +15,7 @@ Install [Roo Code](https://marketplace.visualstudio.com/items?itemName=RooVeteri 4. Enter a valid `Model ID` (for example `qwen3` or `qwen3-coder:480b-cloud`) 5. Adjust the `Context Window` to at least 32K tokens for coding tasks -Coding tools require a larger context window. It is recommended to use a context window of at least 32K tokens. See [Context length](/local/context-length) for more information. +Coding tools require a larger context window. It is recommended to use a context window of at least 32K tokens. See [Context length](/context-length) for more information. ## Connecting to ollama.com diff --git a/docs/integrations/vscode.mdx b/docs/integrations/vscode.mdx index 488d20d66..7d4ef52cf 100644 --- a/docs/integrations/vscode.mdx +++ b/docs/integrations/vscode.mdx @@ -44,7 +44,7 @@ Local models do not require sign-in. VS Code may show a model's maximum supported context length even when Ollama allocates a smaller context at runtime. -For local models, open Ollama **Settings**, set the context length to at least 64k, reload the VS Code window, and resend your prompt. See [Context length](/local/context-length) for more information. +For local models, open Ollama **Settings**, set the context length to at least 64k, reload the VS Code window, and resend your prompt. See [Context length](/context-length) for more information. ## Troubleshooting diff --git a/docs/local/linux.mdx b/docs/linux.mdx similarity index 100% rename from docs/local/linux.mdx rename to docs/linux.mdx diff --git a/docs/local/index.mdx b/docs/local/index.mdx index 7cb107482..dafc22b59 100644 --- a/docs/local/index.mdx +++ b/docs/local/index.mdx @@ -11,19 +11,19 @@ Run models on your own hardware with Ollama. Local inference keeps model executi Choose the installation guide for your environment. - + Install the Ollama app on Apple silicon or Intel hardware. - + Install the native Windows application. - + Install Ollama with the install script or a manual package. - + Run Ollama in a container with CPU or GPU acceleration. @@ -48,10 +48,10 @@ curl http://localhost:11434/api/chat -d '{ ## Configure your environment -- Use the [CLI reference](/local/cli) to run, download, copy, and remove models. -- Adjust the [context length](/local/context-length) for agents and other long-context workloads. -- Review [hardware support](/local/gpu) for GPU compatibility and acceleration. -- [Import a model](/local/import) or create a customized model with a [Modelfile](/local/modelfile). -- Use [local-only mode](/local/faq#how-do-i-disable-ollama-cloud-features) to disable Ollama Cloud features. +- Use the [CLI reference](/cli) to run, download, copy, and remove models. +- Adjust the [context length](/context-length) for agents and other long-context workloads. +- Review [hardware support](/gpu) for GPU compatibility and acceleration. +- [Import a model](/import) or create a customized model with a [Modelfile](/modelfile). +- Use [local-only mode](/faq#how-do-i-disable-ollama-cloud-features) to disable Ollama Cloud features. -For failures, start with [Troubleshooting](/local/troubleshooting). +For failures, start with [Troubleshooting](/troubleshooting). diff --git a/docs/local/macos.mdx b/docs/macos.mdx similarity index 100% rename from docs/local/macos.mdx rename to docs/macos.mdx diff --git a/docs/local/modelfile.mdx b/docs/modelfile.mdx similarity index 100% rename from docs/local/modelfile.mdx rename to docs/modelfile.mdx diff --git a/docs/guide/quickstart.mdx b/docs/quickstart.mdx similarity index 97% rename from docs/guide/quickstart.mdx rename to docs/quickstart.mdx index dbd34c5ed..3297ce828 100644 --- a/docs/guide/quickstart.mdx +++ b/docs/quickstart.mdx @@ -299,4 +299,4 @@ Ollama downloads the model and starts a chat on your computer. Type `/bye` to le ## Next steps -Add [tool calling](/guide/capabilities/tool-calling), [stream responses](/guide/capabilities/streaming), or browse [more models](https://ollama.com/search). +Add [tool calling](/capabilities/tool-calling), [stream responses](/capabilities/streaming), or browse [more models](https://ollama.com/search). diff --git a/docs/local/template.mdx b/docs/template.mdx similarity index 100% rename from docs/local/template.mdx rename to docs/template.mdx diff --git a/docs/local/troubleshooting.mdx b/docs/troubleshooting.mdx similarity index 100% rename from docs/local/troubleshooting.mdx rename to docs/troubleshooting.mdx diff --git a/docs/local/windows.mdx b/docs/windows.mdx similarity index 100% rename from docs/local/windows.mdx rename to docs/windows.mdx From 79f7e3305860feebe63bd7cb5df95a9b9cfabd08 Mon Sep 17 00:00:00 2001 From: Anna Rahn Date: Wed, 7 Oct 2026 12:00:49 -0700 Subject: [PATCH 4/8] changing wording --- .../sample-projects/research-report-agent.mdx | 46 +++++++++---------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/docs/guide/sample-projects/research-report-agent.mdx b/docs/guide/sample-projects/research-report-agent.mdx index c399b969c..26a776d01 100644 --- a/docs/guide/sample-projects/research-report-agent.mdx +++ b/docs/guide/sample-projects/research-report-agent.mdx @@ -4,9 +4,9 @@ sidebarTitle: Research report agent description: Build an Ollama Cloud agent that searches the web, reads primary sources, and produces a cited research report. --- -Build an agent that researches a question and turns its findings into a cited decision report. This is useful for market research, policy summaries, product comparisons, event planning, and other tasks where current sources matter. +Use agents for market research, policy summaries, product comparisons, event planning, and other tasks that depend on current web sources. -The project uses an Ollama Cloud model for reasoning and the Ollama web search and web fetch APIs for research. Inference runs in Ollama Cloud, so you do not need to download the 120B model weights or provide a local GPU. Your local Ollama installation sends requests to the Cloud model. +This project uses an Ollama Cloud model for reasoning and Ollama's web search and web fetch APIs for research. Inference runs in Ollama Cloud, so you do not need to download the 120B model weights or use a local GPU. Your local Ollama installation sends requests to the Cloud model. ## What you will build @@ -14,13 +14,13 @@ Given a question such as: > What have four-day workweek pilots since 2022 reported about employee wellbeing and business performance? -the agent will: +The agent: -1. Turn the question into several focused searches. -2. Search the web and choose promising results. -3. Fetch source pages for more context. -4. Compare claims across sources. -5. Write a report with links, caveats, and suggested follow-up questions. +1. Turns the question into several focused searches. +2. Searches the web and choose promising results. +3. Fetches source pages for more context. +4. Compares claims across sources. +5. Writes a report with links, caveats, and suggested follow-up questions. The tutorial uses `gpt-oss:120b-cloud` throughout. @@ -28,12 +28,12 @@ The tutorial uses `gpt-oss:120b-cloud` throughout. You need: -- [Ollama installed](https://ollama.com/download) - Python 3.10 or later +- [Ollama installed](https://ollama.com/download) - An [Ollama account](https://ollama.com) - An [Ollama API key](https://ollama.com/settings/keys) -Signing in to Ollama gives your local installation access to the Cloud model. The API key gives the script access to the [web search tools](/capabilities/web-search). Treat the API key like a password and do not add it to source control. +Signing in gives your local Ollama installation access to the Cloud model. The API key gives the script access to the [web search tools](/capabilities/web-search). Treat the key like a password and never add it to source control. ## 1. Set up the project @@ -88,7 +88,7 @@ $env:OLLAMA_API_KEY="your_api_key" - Environment variables set this way last only for the current terminal session. Use your operating system's secret manager for a persistent setup. + These environment variables last only for the current terminal session. For a persistent setup, use your operating system's secret manager. ## 2. Pull and test the Cloud model @@ -105,9 +105,9 @@ Pull `gpt-oss:120b-cloud`: ollama pull gpt-oss:120b-cloud ``` -This downloads the Cloud model configuration, not the 120B model weights. The model runs on Ollama's infrastructure when you use it. +This downloads the Cloud model configuration, not the 120B model weights. Ollama runs the model in the cloud when you use it. -Send a test prompt to confirm that the model is ready: +Send a test prompt to confirm the model is ready: ```shell ollama run gpt-oss:120b-cloud "Reply with exactly: Cloud model ready" @@ -119,7 +119,7 @@ You should receive: Cloud model ready ``` -The research agent will use this same model through the Ollama Python library. +The research agent uses the same model through the Ollama Python library. ## 3. Create the agent @@ -307,11 +307,11 @@ if __name__ == "__main__": save_report(report) ``` -The model receives the functions in `TOOLS`, decides when to call them, and uses their results in later turns. When research ends, the script accepts a non-empty report or runs `create_final_report` without tools. +The model receives the functions in `TOOLS`, decides when to call them, and uses the results in later turns. When research ends, the script accepts a non-empty report or runs `create_final_report` without tools. -Search results sometimes point to pages that have moved, reject automated access, or no longer exist. The error handlers return those failures to the model as tool results so it can search for another source instead of stopping the program. +Search results can point to pages that moved, reject automated access, or no longer exist. The error handlers return these failures to the model as tool results, allowing the agent to find another source without stopping the program. -`MAX_TOOL_ROUNDS` prevents an open-ended research loop. `create_final_report` disables thinking output and retries once if the model returns empty content. The script raises an error instead of creating an empty file if both attempts are empty. +`MAX_TOOL_ROUNDS` limits the research loop. `create_final_report` disables thinking output and retries once if the model returns empty content. If both attempts are empty, the script raises an error instead of creating an empty file. ## 4. Run the project @@ -327,7 +327,7 @@ Or provide your own question: python research_agent.py "What evidence supports later high school start times?" ``` -During the run, the script prints each tool call. A typical trace looks like this: +The script prints each tool call as it runs. A typical trace looks like this: ```text Tool: web_search({'query': 'four-day workweek pilot 2022 study results'}) @@ -336,19 +336,19 @@ Tool: web_fetch({'url': 'https://example.org/report'}) Tool error: web_fetch failed with HTTP 404: not found. Do not cite this result. Try another search result or URL. ``` -Search queries, sources, and occasional fetch errors will vary between runs. That is expected: the model chooses its next action from the evidence it has already gathered. A failed fetch should be followed by another search or source selection rather than a Python traceback. +Search queries, sources, and occasional fetch errors vary between runs. The model chooses each next action from the evidence it has gathered. After a failed fetch, it should search again or select another source instead of returning a Python traceback. ## 5. Review the result -The first run creates an `output` directory next to `research_agent.py`. Later runs reuse the same directory. Each report is saved as a timestamped Markdown file, for example: +The first run creates an `output` directory next to `research_agent.py`. Later runs reuse it. Each report is saved as a timestamped Markdown file, for example: ```text output/Research report 2026-10-06_15-45-12.md ``` -The complete Markdown report is printed to the terminal before it is saved. Empty output is treated as an error, so the script will not create a blank report file. +The script prints the complete Markdown report to the terminal before saving it. It treats empty output as an error and does not create a blank report file. -Expect a Markdown report with this general shape in the `./output/` folder: +The `./output/` folder contains a Markdown report with this structure: ```text # Research report @@ -369,7 +369,7 @@ Actions or questions that follow from the evidence. A list of the pages used in the report. ``` -The first run should produce a useful draft, not an unquestionable final answer. Check that links open, quoted numbers match their sources, and the report distinguishes published evidence from the model's interpretation. +The first run produces a useful draft, not a final authority. Check that links open, quoted numbers match their sources, and the report separates published evidence from the model's interpretation. Web results can be incomplete, outdated, or wrong. Review the original sources before using the report for medical, legal, financial, employment, or other high-impact decisions. From 9062a9a2e6ad01cde1f0a26926e3204a0ffb3fec Mon Sep 17 00:00:00 2001 From: Anna Rahn Date: Wed, 7 Oct 2026 12:11:19 -0700 Subject: [PATCH 5/8] removing repetition, fixing a typo --- docs/guide/sample-projects/research-report-agent.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/guide/sample-projects/research-report-agent.mdx b/docs/guide/sample-projects/research-report-agent.mdx index 26a776d01..2a77fcad7 100644 --- a/docs/guide/sample-projects/research-report-agent.mdx +++ b/docs/guide/sample-projects/research-report-agent.mdx @@ -17,7 +17,7 @@ Given a question such as: The agent: 1. Turns the question into several focused searches. -2. Searches the web and choose promising results. +2. Searches the web and chooses promising results. 3. Fetches source pages for more context. 4. Compares claims across sources. 5. Writes a report with links, caveats, and suggested follow-up questions. @@ -392,7 +392,6 @@ Try these changes after the basic project works: - Change `SYSTEM_PROMPT` to require a particular audience, length, or report format. - Ask the agent to prefer sources from specific domains or a date range. - Increase `MAX_TOOL_ROUNDS` for broader research, or decrease it for faster, more focused runs. -- Save the final string to a Markdown file for sharing. - Add a human approval step before the agent fetches unfamiliar domains. See [Tool calling](/capabilities/tool-calling) for more agent-loop patterns and [Web search](/capabilities/web-search) for the complete search and fetch interfaces. From 539c4a07a53b4f8838c715ef6deef3585f7cb307 Mon Sep 17 00:00:00 2001 From: Anna Rahn Date: Wed, 7 Oct 2026 12:15:54 -0700 Subject: [PATCH 6/8] re-ordering top nav, splitting out sample project into new PR --- docs/docs.json | 78 ++-- .../sample-projects/research-report-agent.mdx | 397 ------------------ 2 files changed, 32 insertions(+), 443 deletions(-) delete mode 100644 docs/guide/sample-projects/research-report-agent.mdx diff --git a/docs/docs.json b/docs/docs.json index 39e2217fa..ace0d4a2c 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -144,14 +144,6 @@ "source": "/guide/capabilities/web-search", "destination": "/capabilities/web-search" }, - { - "source": "/sample-projects/research-brief-agent", - "destination": "/guide/sample-projects/research-report-agent" - }, - { - "source": "/guide/sample-projects/research-brief-agent", - "destination": "/guide/sample-projects/research-report-agent" - }, { "source": "/local/cli", "destination": "/cli" @@ -225,11 +217,41 @@ "/capabilities/tool-calling", "/capabilities/web-search" ] + } + ] + }, + { + "tab": "API Reference", + "openapi": "/openapi.yaml", + "groups": [ + { + "group": "API Reference", + "pages": [ + "/api/introduction", + "/api/authentication", + "/api/streaming", + "/api/usage", + "/api/errors", + "/api/openai-compatibility", + "/api/anthropic-compatibility" + ] }, { - "group": "Sample projects", + "group": "Endpoints", "pages": [ - "/guide/sample-projects/research-report-agent" + "POST /api/generate", + "POST /api/chat", + "POST /api/embed", + "POST /v1/systemone", + "GET /api/tags", + "GET /api/ps", + "POST /api/show", + "POST /api/create", + "POST /api/copy", + "POST /api/pull", + "POST /api/push", + "DELETE /api/delete", + "GET /api/version" ] } ] @@ -365,42 +387,6 @@ ] } ] - }, - { - "tab": "API Reference", - "openapi": "/openapi.yaml", - "groups": [ - { - "group": "API Reference", - "pages": [ - "/api/introduction", - "/api/authentication", - "/api/streaming", - "/api/usage", - "/api/errors", - "/api/openai-compatibility", - "/api/anthropic-compatibility" - ] - }, - { - "group": "Endpoints", - "pages": [ - "POST /api/generate", - "POST /api/chat", - "POST /api/embed", - "POST /v1/systemone", - "GET /api/tags", - "GET /api/ps", - "POST /api/show", - "POST /api/create", - "POST /api/copy", - "POST /api/pull", - "POST /api/push", - "DELETE /api/delete", - "GET /api/version" - ] - } - ] } ] } diff --git a/docs/guide/sample-projects/research-report-agent.mdx b/docs/guide/sample-projects/research-report-agent.mdx deleted file mode 100644 index 2a77fcad7..000000000 --- a/docs/guide/sample-projects/research-report-agent.mdx +++ /dev/null @@ -1,397 +0,0 @@ ---- -title: Build a research report agent -sidebarTitle: Research report agent -description: Build an Ollama Cloud agent that searches the web, reads primary sources, and produces a cited research report. ---- - -Use agents for market research, policy summaries, product comparisons, event planning, and other tasks that depend on current web sources. - -This project uses an Ollama Cloud model for reasoning and Ollama's web search and web fetch APIs for research. Inference runs in Ollama Cloud, so you do not need to download the 120B model weights or use a local GPU. Your local Ollama installation sends requests to the Cloud model. - -## What you will build - -Given a question such as: - -> What have four-day workweek pilots since 2022 reported about employee wellbeing and business performance? - -The agent: - -1. Turns the question into several focused searches. -2. Searches the web and chooses promising results. -3. Fetches source pages for more context. -4. Compares claims across sources. -5. Writes a report with links, caveats, and suggested follow-up questions. - -The tutorial uses `gpt-oss:120b-cloud` throughout. - -## Before you begin - -You need: - -- Python 3.10 or later -- [Ollama installed](https://ollama.com/download) -- An [Ollama account](https://ollama.com) -- An [Ollama API key](https://ollama.com/settings/keys) - -Signing in gives your local Ollama installation access to the Cloud model. The API key gives the script access to the [web search tools](/capabilities/web-search). Treat the key like a password and never add it to source control. - -## 1. Set up the project - -Create a project directory and a Python virtual environment: - - - - -```shell -mkdir research-report-agent -cd research-report-agent -python3 -m venv .venv -source .venv/bin/activate -``` - - - - -```powershell -mkdir research-report-agent -cd research-report-agent -py -m venv .venv -.venv\Scripts\Activate.ps1 -``` - - - - -Install the Ollama Python library: - -```shell -pip install --upgrade ollama -``` - -Set your API key for the current terminal session: - - - - -```shell -export OLLAMA_API_KEY=your_api_key -``` - - - - -```powershell -$env:OLLAMA_API_KEY="your_api_key" -``` - - - - - - These environment variables last only for the current terminal session. For a persistent setup, use your operating system's secret manager. - - -## 2. Pull and test the Cloud model - -Sign in to your Ollama account: - -```shell -ollama signin -``` - -Pull `gpt-oss:120b-cloud`: - -```shell -ollama pull gpt-oss:120b-cloud -``` - -This downloads the Cloud model configuration, not the 120B model weights. Ollama runs the model in the cloud when you use it. - -Send a test prompt to confirm the model is ready: - -```shell -ollama run gpt-oss:120b-cloud "Reply with exactly: Cloud model ready" -``` - -You should receive: - -```text -Cloud model ready -``` - -The research agent uses the same model through the Ollama Python library. - -## 3. Create the agent - -Save the following as `research_agent.py`: - -```python -import os -import sys -from datetime import datetime -from pathlib import Path - -from ollama import Client, RequestError, ResponseError, web_fetch, web_search - - -# The ":cloud" suffix tells Ollama to run this model in Ollama Cloud -# The "120b" tells Ollama what quantization level to use -MODEL = "gpt-oss:120b-cloud" -MAX_TOOL_ROUNDS = 8 -MAX_SOURCE_CHARS = 12000 - -DEFAULT_QUESTION = ( - "What have four-day workweek pilots since 2022 reported about " - "employee wellbeing and business performance?" -) - -# These are the only tools the model is allowed to call -TOOLS = { - "web_search": web_search, - "web_fetch": web_fetch, -} - -SYSTEM_PROMPT = """You are a careful research agent. - -Research the user's question before answering. Search broadly, then fetch the -most useful pages. Prefer primary sources, original studies, official reports, -and sources that clearly explain their methods. -Only call web_fetch with an exact URL returned by web_search. Never guess or -construct a source URL. - -Your final answer must contain: -1. An executive summary -2. Key findings, including disagreements between sources -3. Limitations and missing evidence -4. Practical next steps -5. A Sources section with Markdown links - -Attach a source link to every important factual claim. Never invent a citation. -If the available evidence does not support a conclusion, say so explicitly. -""" - -FINAL_REPORT_PROMPT = """Using the research above, write the complete cited -report now. Return only the Markdown report and do not call more tools.""" - - -def run_tool(name: str, arguments: dict) -> str: - """Run a tool requested by the model and return its result as text.""" - tool = TOOLS.get(name) - if tool is None: - return f"Unknown tool: {name}" - - print(f"Tool: {name}({arguments})", flush=True) - - try: - result = tool(**arguments) - except ResponseError as error: - # A page may have moved or may reject automated access. Returning the - # error lets the model search for another source instead of crashing - message = ( - f"{name} failed with HTTP {error.status_code}: {error.error}. " - "Do not cite this result. Try another search result or URL." - ) - print(f"Tool error: {message}", flush=True) - return message - except RequestError as error: - message = ( - f"{name} could not reach the service: {error}. " - "Try the request again or use another source." - ) - print(f"Tool error: {message}", flush=True) - return message - - # Limit long pages so one source does not fill the model's context window - return str(result)[:MAX_SOURCE_CHARS] - - -def create_final_report(client: Client, messages: list) -> str: - """Ask the model for the final report, retrying once if it is empty.""" - final_messages = messages + [ - {"role": "user", "content": FINAL_REPORT_PROMPT} - ] - - for _ in range(2): - # Omitting tools prevents the model from doing more research here - response = client.chat( - model=MODEL, - messages=final_messages, - think=False, - ) - report = response.message.content or "" - if report.strip(): - return report - - # Keep the empty response in the conversation, then ask once more - final_messages += [ - response.message, - { - "role": "user", - "content": "Your response was empty. Write the Markdown report now.", - }, - ] - - raise RuntimeError("The Cloud model returned an empty report twice.") - - -def research(question: str) -> str: - """Research a question and return a non-empty Markdown report.""" - # The web search and fetch APIs use this key automatically - if not os.environ.get("OLLAMA_API_KEY"): - raise RuntimeError("Set OLLAMA_API_KEY before running the agent.") - - # Client() connects to the local Ollama app. Ollama routes the :cloud model - # to Ollama Cloud because you signed in during setup - client = Client() - - # messages stores the complete conversation, including tool results - messages = [ - {"role": "system", "content": SYSTEM_PROMPT}, - {"role": "user", "content": question}, - ] - - for _ in range(MAX_TOOL_ROUNDS): - response = client.chat( - model=MODEL, - messages=messages, - tools=list(TOOLS.values()), - think=True, - ) - messages.append(response.message) - - tool_calls = response.message.tool_calls or [] - if not tool_calls: - # The model may return the finished report during the tool loop - report = response.message.content or "" - if report.strip(): - return report - break - - # Run every requested tool and send each result back to the model - for call in tool_calls: - name = call.function.name - result = run_tool(name, call.function.arguments) - messages.append( - { - "role": "tool", - "tool_name": name, - "content": result, - } - ) - - # This also runs when the agent reaches MAX_TOOL_ROUNDS - return create_final_report(client, messages) - - -def save_report(report: str) -> None: - """Save the report in a reusable output directory beside this script.""" - output_dir = Path(__file__).resolve().parent / "output" - output_dir.mkdir(exist_ok=True) - - timestamp = datetime.now().strftime("%Y-%m-%d_%H-%M-%S") - output_path = output_dir / f"Research report {timestamp}.md" - output_path.write_text(report, encoding="utf-8") - - -if __name__ == "__main__": - # Text after the script name (research_agent.py) becomes the research question. If no - # text is provided, the tutorial's default question is used - question = " ".join(sys.argv[1:]) or DEFAULT_QUESTION - report = research(question) - - # Never print or save a blank report - if not report.strip(): - raise RuntimeError("The research agent returned an empty report.") - - print(report, flush=True) - save_report(report) -``` - -The model receives the functions in `TOOLS`, decides when to call them, and uses the results in later turns. When research ends, the script accepts a non-empty report or runs `create_final_report` without tools. - -Search results can point to pages that moved, reject automated access, or no longer exist. The error handlers return these failures to the model as tool results, allowing the agent to find another source without stopping the program. - -`MAX_TOOL_ROUNDS` limits the research loop. `create_final_report` disables thinking output and retries once if the model returns empty content. If both attempts are empty, the script raises an error instead of creating an empty file. - -## 4. Run the project - -Run the agent with the example research question: - -```shell -python research_agent.py -``` - -Or provide your own question: - -```shell -python research_agent.py "What evidence supports later high school start times?" -``` - -The script prints each tool call as it runs. A typical trace looks like this: - -```text -Tool: web_search({'query': 'four-day workweek pilot 2022 study results'}) -Tool: web_search({'query': 'four-day week trial company revenue retention report'}) -Tool: web_fetch({'url': 'https://example.org/report'}) -Tool error: web_fetch failed with HTTP 404: not found. Do not cite this result. Try another search result or URL. -``` - -Search queries, sources, and occasional fetch errors vary between runs. The model chooses each next action from the evidence it has gathered. After a failed fetch, it should search again or select another source instead of returning a Python traceback. - -## 5. Review the result - -The first run creates an `output` directory next to `research_agent.py`. Later runs reuse it. Each report is saved as a timestamped Markdown file, for example: - -```text -output/Research report 2026-10-06_15-45-12.md -``` - -The script prints the complete Markdown report to the terminal before saving it. It treats empty output as an error and does not create a blank report file. - -The `./output/` folder contains a Markdown report with this structure: - -```text -# Research report - -## Executive summary -A concise answer to the research question. - -## Key findings -Findings grouped by theme, with links attached to factual claims. - -## Limitations -Gaps in the available evidence, methodology concerns, and conflicting results. - -## Practical next steps -Actions or questions that follow from the evidence. - -## Sources -A list of the pages used in the report. -``` - -The first run produces a useful draft, not a final authority. Check that links open, quoted numbers match their sources, and the report separates published evidence from the model's interpretation. - - - Web results can be incomplete, outdated, or wrong. Review the original sources before using the report for medical, legal, financial, employment, or other high-impact decisions. - - -## What happens at each stage - -| Stage | What the Cloud model does | What you should expect | -| --- | --- | --- | -| Plan | Breaks the question into searchable claims | Several queries covering different aspects of the topic | -| Search | Calls `web_search` and evaluates result snippets | A visible tool trace; some searches may be discarded | -| Read | Calls `web_fetch` for promising pages | More detailed evidence from a smaller set of sources | -| Compare | Looks for agreement, conflicts, and missing context | Findings that separate strong evidence from uncertainty | -| Synthesize | Writes the requested report | A readable report with citations, caveats, and next steps | - -## Improve the agent - -Try these changes after the basic project works: - -- Change `SYSTEM_PROMPT` to require a particular audience, length, or report format. -- Ask the agent to prefer sources from specific domains or a date range. -- Increase `MAX_TOOL_ROUNDS` for broader research, or decrease it for faster, more focused runs. -- Add a human approval step before the agent fetches unfamiliar domains. - -See [Tool calling](/capabilities/tool-calling) for more agent-loop patterns and [Web search](/capabilities/web-search) for the complete search and fetch interfaces. From db2635b54b541104d5c574ed4cbb9bd7a91632f8 Mon Sep 17 00:00:00 2001 From: Anna Rahn Date: Thu, 8 Oct 2026 15:12:00 -0700 Subject: [PATCH 7/8] standardizing language referring to cloud services --- docs/README.md | 2 +- docs/api/introduction.mdx | 16 +++++----------- docs/capabilities/structured-outputs.mdx | 2 +- docs/cloud.mdx | 6 +++--- docs/cloud/api.mdx | 2 +- docs/cloud/faq.mdx | 4 ++-- docs/cloud/model-lifecycle.mdx | 2 +- docs/cloud/models.mdx | 4 ++-- docs/faq.mdx | 2 +- docs/integrations/claude-code.mdx | 2 +- docs/integrations/deepseek-harness.mdx | 2 +- docs/integrations/droid.mdx | 4 ++-- docs/integrations/marimo.mdx | 2 +- docs/integrations/onyx.mdx | 4 ++-- docs/local/index.mdx | 2 +- docs/openapi.yaml | 4 ++-- 16 files changed, 27 insertions(+), 33 deletions(-) diff --git a/docs/README.md b/docs/README.md index f11addb3f..bd531aea8 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,7 +3,7 @@ ### Getting started * [Quickstart](https://docs.ollama.com/quickstart) -* [Ollama Cloud](https://docs.ollama.com/cloud) +* [Ollama's cloud](https://docs.ollama.com/cloud) * [Run Ollama locally](https://docs.ollama.com/local) * [Examples](./examples.md) diff --git a/docs/api/introduction.mdx b/docs/api/introduction.mdx index 80ba0b90a..640e815d9 100644 --- a/docs/api/introduction.mdx +++ b/docs/api/introduction.mdx @@ -1,21 +1,15 @@ --- title: Introduction -description: Use the Ollama API locally or through Ollama Cloud with a shared request format. +description: Use the Ollama API locally or with Ollama's cloud models. --- -Use Ollama's API to build applications with cloud or local models. +Use Ollama's API to build applications with local or cloud models. ## Get started -Choose how the request reaches the model: +Call cloud models with an [API key](https://ollama.com/settings/keys). No Ollama installation required. Start with the [API quickstart](/quickstart#build-an-application). -| Access path | Model runs on | Base URL | Authentication and model name | -| --- | --- | --- | --- | -| [Local model](/local) | Your hardware | `http://localhost:11434/api` | None by default; use the local model name | -| [Cloud model through Ollama](/cloud/models) | Ollama Cloud | `http://localhost:11434/api` | Run `ollama signin`; use a model name ending in `:cloud` | -| [Direct Cloud API](/cloud/api) | Ollama Cloud | `https://ollama.com/api` | Send an Ollama API key; use the Cloud API model name | - -Request bodies have the same shape for shared endpoints. The host, authentication, and model name depend on the access path. +To run models on your computer, [install Ollama and run a local model](/quickstart#run-a-model-locally). ## Base URLs @@ -29,7 +23,7 @@ The Anthropic client appends `/v1/messages` to its base URL. Cloud requests need an API key. Local requests do not. To use cloud models through your local server, [sign in to Ollama](/api/authentication#signing-in). -Creating or deleting models requires a local Ollama server. [System One](/capabilities/decision) also requires a local server and is not yet available on Ollama Cloud. For supported API features, see [OpenAI compatibility](/api/openai-compatibility) and [Anthropic compatibility](/api/anthropic-compatibility). +Creating or deleting models requires a local Ollama server. [System One](/capabilities/decision) also requires a local server and is not yet available on cloud. For supported API features, see [OpenAI compatibility](/api/openai-compatibility) and [Anthropic compatibility](/api/anthropic-compatibility). ## Ollama API example diff --git a/docs/capabilities/structured-outputs.mdx b/docs/capabilities/structured-outputs.mdx index c570a12f9..5a2df685b 100644 --- a/docs/capabilities/structured-outputs.mdx +++ b/docs/capabilities/structured-outputs.mdx @@ -3,7 +3,7 @@ title: Structured Outputs --- - Ollama's Cloud currently does not support structured outputs. + Ollama's cloud currently does not support structured outputs. Structured outputs let you enforce a JSON schema on model responses so you can reliably extract structured data, describe images, or keep every reply consistent. diff --git a/docs/cloud.mdx b/docs/cloud.mdx index 7f8d24e00..a9c06d26d 100644 --- a/docs/cloud.mdx +++ b/docs/cloud.mdx @@ -1,10 +1,10 @@ --- -title: Ollama Cloud +title: Ollama's cloud sidebarTitle: Overview -description: Choose how to run Ollama Cloud models through the Ollama CLI, a local API, or the direct Cloud API. +description: Choose how to run Ollama's cloud models through the Ollama CLI, a local API, or the direct cloud API. --- -Ollama Cloud runs larger models without requiring a powerful GPU. Cloud models support the same capabilities as local models, but inference runs on Ollama's cloud service. +Ollama's cloud runs larger models without requiring a powerful GPU. Cloud models support the same capabilities as local models, but inference runs on Ollama's cloud service. ## Choose how to connect diff --git a/docs/cloud/api.mdx b/docs/cloud/api.mdx index 055434ab9..86c02e713 100644 --- a/docs/cloud/api.mdx +++ b/docs/cloud/api.mdx @@ -1,6 +1,6 @@ --- title: Cloud API -description: Authenticate and call the Ollama Cloud API directly at https://ollama.com/api. +description: Authenticate and call Ollama's cloud API directly at https://ollama.com/api. --- Call Cloud models directly through `https://ollama.com/api`. In this mode, `ollama.com` is the Ollama host and a local Ollama installation is not required. diff --git a/docs/cloud/faq.mdx b/docs/cloud/faq.mdx index e5b2a1a61..2c2ca395d 100644 --- a/docs/cloud/faq.mdx +++ b/docs/cloud/faq.mdx @@ -1,7 +1,7 @@ --- title: Cloud FAQ sidebarTitle: FAQ -description: Frequently asked questions about Ollama Cloud accounts, authentication, privacy, and requests. +description: Frequently asked questions about Ollama's cloud models, accounts, authentication, privacy, and requests. --- For questions about installation, hardware, and the local Ollama server, see the [Local FAQ](/faq). @@ -40,7 +40,7 @@ You need it to: - Push models to Ollama - Pull private models to your machine -- Run models hosted in Ollama Cloud through your local Ollama installation +- Run models hosted in Ollama's cloud through your local Ollama installation ### Add the key to your account diff --git a/docs/cloud/model-lifecycle.mdx b/docs/cloud/model-lifecycle.mdx index 3170b847f..bbeeb1ebe 100644 --- a/docs/cloud/model-lifecycle.mdx +++ b/docs/cloud/model-lifecycle.mdx @@ -1,6 +1,6 @@ --- title: Cloud model lifecycle -description: Review upcoming and past Ollama Cloud model retirements and recommended replacements. +description: Review upcoming and past retirements of Ollama's cloud models and recommended replacements. --- Ollama occasionally deprecates and retires older Cloud models as newer models become available. Tools and applications that depend on a retired model must be updated to use another model. diff --git a/docs/cloud/models.mdx b/docs/cloud/models.mdx index ffbd86768..8f2f19081 100644 --- a/docs/cloud/models.mdx +++ b/docs/cloud/models.mdx @@ -1,10 +1,10 @@ --- title: Use Cloud models from Ollama sidebarTitle: Cloud models -description: Run Ollama Cloud models from the CLI, the local Ollama API, or the official Python and JavaScript libraries. +description: Run Ollama's cloud models from the CLI, the local Ollama API, or the official Python and JavaScript libraries. --- -Cloud models are automatically offloaded to Ollama Cloud while remaining available to local tools and integrations through Ollama. +Cloud models are automatically offloaded to Ollama's cloud while remaining available to local tools and integrations through Ollama. ## Sign in diff --git a/docs/faq.mdx b/docs/faq.mdx index 452c21cc0..4531b9f7a 100644 --- a/docs/faq.mdx +++ b/docs/faq.mdx @@ -160,7 +160,7 @@ docker build -t ollama-with-ca . docker run -d -e HTTPS_PROXY=https://my.proxy.example.com -p 11434:11434 ollama-with-ca ``` -## How do I disable Ollama Cloud features? +## How do I disable Ollama's cloud features? {#how-do-i-disable-ollama-cloud-features} Ollama can run in local only mode by disabling Ollama's cloud features. By turning off Ollama's cloud features, you will lose the ability to use Ollama's cloud models and web search. diff --git a/docs/integrations/claude-code.mdx b/docs/integrations/claude-code.mdx index b27b8834f..93d234871 100644 --- a/docs/integrations/claude-code.mdx +++ b/docs/integrations/claude-code.mdx @@ -155,7 +155,7 @@ Claude Code prompts for permission on most actions. To allow the bot to work aut See the [plugin README](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins/telegram) for setup instructions. -## Connect directly to Ollama Cloud +## Connect directly to Ollama's cloud Install Claude Code, then set your [API key](/quickstart#build-an-application) in `OLLAMA_API_KEY`. No Ollama installation required. diff --git a/docs/integrations/deepseek-harness.mdx b/docs/integrations/deepseek-harness.mdx index c09ff9817..1f659654f 100644 --- a/docs/integrations/deepseek-harness.mdx +++ b/docs/integrations/deepseek-harness.mdx @@ -27,7 +27,7 @@ ollama launch dsh --config ## Web search -Web search is enabled automatically. It requires Ollama cloud access and a model that supports tools. Run `ollama signin` if needed. +Web search is enabled automatically. It requires access to Ollama's cloud and a model that supports tools. Run `ollama signin` if needed. ## Configuration diff --git a/docs/integrations/droid.mdx b/docs/integrations/droid.mdx index 249554510..7ea182d46 100644 --- a/docs/integrations/droid.mdx +++ b/docs/integrations/droid.mdx @@ -56,7 +56,7 @@ Add the cloud configuration block to `~/.factory/config.json`: { "custom_models": [ { - "model_display_name": "qwen3-coder [Ollama Cloud]", + "model_display_name": "qwen3-coder [Ollama's cloud]", "model": "qwen3-coder:480b-cloud", "base_url": "http://localhost:11434/v1/", "api_key": "not-needed", @@ -76,7 +76,7 @@ Add the cloud configuration block to `~/.factory/config.json`: { "custom_models": [ { - "model_display_name": "qwen3-coder [Ollama Cloud]", + "model_display_name": "qwen3-coder [Ollama's cloud]", "model": "qwen3-coder:480b", "base_url": "https://ollama.com/v1/", "api_key": "OLLAMA_API_KEY", diff --git a/docs/integrations/marimo.mdx b/docs/integrations/marimo.mdx index 33815891b..73516cb47 100644 --- a/docs/integrations/marimo.mdx +++ b/docs/integrations/marimo.mdx @@ -68,6 +68,6 @@ would typically point the base url to `http://localhost:11434/v1`. ## Connecting to ollama.com -1. Sign in to ollama cloud via `ollama signin` +1. Sign in to Ollama's cloud with `ollama signin` 2. In the ollama model settings add a model that ollama hosts, like `gpt-oss:120b`. 3. You can now refer to this model in marimo! diff --git a/docs/integrations/onyx.mdx b/docs/integrations/onyx.mdx index e0587efb2..b5235ed37 100644 --- a/docs/integrations/onyx.mdx +++ b/docs/integrations/onyx.mdx @@ -51,7 +51,7 @@ Resourcing/scaling docs [here](https://docs.onyx.app/deployment/getting_started/ />
-You can also easily connect up Onyx Cloud with the `Ollama Cloud` tab of the setup. +You can also connect Onyx Cloud to Ollama's cloud from the setup flow. ## Send your first query
@@ -60,4 +60,4 @@ You can also easily connect up Onyx Cloud with the `Ollama Cloud` tab of the set alt="Onyx Query Example" width="75%" /> -
\ No newline at end of file +
diff --git a/docs/local/index.mdx b/docs/local/index.mdx index dafc22b59..38520aadd 100644 --- a/docs/local/index.mdx +++ b/docs/local/index.mdx @@ -52,6 +52,6 @@ curl http://localhost:11434/api/chat -d '{ - Adjust the [context length](/context-length) for agents and other long-context workloads. - Review [hardware support](/gpu) for GPU compatibility and acceleration. - [Import a model](/import) or create a customized model with a [Modelfile](/modelfile). -- Use [local-only mode](/faq#how-do-i-disable-ollama-cloud-features) to disable Ollama Cloud features. +- Use [local-only mode](/faq#how-do-i-disable-ollama-cloud-features) to disable Ollama's cloud features. For failures, start with [Troubleshooting](/troubleshooting). diff --git a/docs/openapi.yaml b/docs/openapi.yaml index 675c8bb59..df7550579 100644 --- a/docs/openapi.yaml +++ b/docs/openapi.yaml @@ -2118,7 +2118,7 @@ paths: operationId: usage servers: - url: https://ollama.com - description: Ollama Cloud + description: Ollama's cloud security: - bearerAuth: [] parameters: @@ -2186,7 +2186,7 @@ paths: operationId: balance servers: - url: https://ollama.com - description: Ollama Cloud + description: Ollama's cloud security: - bearerAuth: [] responses: From 735696814bb9bbfb51bac6400d2fa335ec284c1b Mon Sep 17 00:00:00 2001 From: Anna Rahn Date: Mon, 12 Oct 2026 11:02:05 -0700 Subject: [PATCH 8/8] typo in docs --- docs/cloud/api.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cloud/api.mdx b/docs/cloud/api.mdx index 86c02e713..4aa232d59 100644 --- a/docs/cloud/api.mdx +++ b/docs/cloud/api.mdx @@ -3,7 +3,7 @@ title: Cloud API description: Authenticate and call Ollama's cloud API directly at https://ollama.com/api. --- -Call Cloud models directly through `https://ollama.com/api`. In this mode, `ollama.com` is the Ollama host and a local Ollama installation is not required. +Call cloud models directly through `https://ollama.com/api`. In this mode, `ollama.com` is the Ollama host and a local Ollama installation is not required. ## Authentication