CAMEL-23500: Document camel-openai usage with OpenAI-compatible providers by k-krawczyk · Pull Request #23614 · apache/camel

k-krawczyk · 2026-05-28T22:08:28Z

Summary

Adds an "OpenAI-Compatible Providers" section to the OpenAI component documentation, with baseUrl-based configuration examples for OpenRouter, Ollama, LM Studio, and vLLM. This makes it discoverable that no separate component is needed to use third-party gateways or local model servers.

Changes

New == OpenAI-Compatible Providers section in openai-component.adoc:
- Provider → baseUrl reference table (OpenAI, OpenRouter, Ollama, LM Studio, vLLM)
- Per-provider examples (Ollama, LM Studio, vLLM)
- OpenRouter: cross-provider model identifiers and provider routing/fallbacks via additionalBodyProperty (a JSON body value)

Docs-only; no code changes. The docs/components/.../openai-component.adoc page is a symlink to the component source, so only the source file changes.

On the OpenRouter attribution headers

The ticket also asked to document setting OpenRouter's HTTP-Referer / X-Title attribution headers via exchange headers. After checking the code, the component does not currently expose a way to set custom HTTP request headers: the client is built with only apiKey/baseUrl/SSL and the producer calls .create(params) without RequestOptions. So I documented this as a current limitation rather than referencing a non-existent option. I'd suggest a small follow-up enhancement to add a custom request-header option (e.g. additionalRequestHeader.), which the openai-java SDK supports via RequestOptions.putHeader — happy to take that on.

On a dedicated OpenRouter kamelet

The ticket asked to evaluate one. Given baseUrl reduces OpenRouter to a one-line configuration, a dedicated kamelet adds little value over the documented approach, so I'd lean against it.

Reported by Claude Code on behalf of Karol Krawczyk

gnodet

Documentation-only addition — well-written guide for using camel-openai with OpenAI-compatible providers (Ollama, LM Studio, vLLM, OpenRouter). The provider routing example for OpenRouter with additionalBodyProperty.provider is particularly useful, and the note about the limitation with custom HTTP headers is transparent.

Good use of AsciiDoc tabs for Java/YAML examples. Provider table is clean and actionable.

LGTM.

Fully automatic review from Claude Code

github-actions · 2026-05-29T05:59:42Z

🌟 Thank you for your contribution to the Apache Camel project! 🌟
🤖 CI automation will test this PR automatically.

🐫 Apache Camel Committers, please review the following items:

First-time contributors require MANUAL approval for the GitHub Actions to run
You can use the command /component-test (camel-)component-name1 (camel-)component-name2.. to request a test from the test bot although they are normally detected and executed by CI.
You can label PRs using skip-tests and test-dependents to fine-tune the checks executed by this PR.
Build and test logs are available in the summary page. Only Apache Camel committers have access to the summary.

⚠️ Be careful when sharing logs. Review their contents before sharing them publicly.

github-actions · 2026-05-29T06:15:37Z

🧪 CI tested the following changed modules:

components/camel-ai/camel-openai

⚠️ Some tests are disabled on GitHub Actions (@DisabledIfSystemProperty(named = "ci.env.name")) and require manual verification:

components/camel-ai/camel-openai: 6 test(s) disabled on GitHub Actions

All tested modules (8 modules)

Camel :: AI :: OpenAI
Camel :: JBang :: MCP
Camel :: JBang :: Plugin :: Route Parser
Camel :: JBang :: Plugin :: TUI
Camel :: JBang :: Plugin :: Validate
Camel :: Launcher :: Container
Camel :: YAML DSL :: Validator
Camel :: YAML DSL :: Validator Maven Plugin

⚙️ View full build and test results

Croway · 2026-05-29T08:13:54Z

Hi @k-krawczyk thanks for your contribution! I added a couple of comments

davsclaus · 2026-05-30T06:25:24Z

@Croway I cannot see your questions here on github

Croway · 2026-05-30T13:16:21Z

@davsclaus uh, that is strange, I can see those both in the conversation page, and the Files changed

k-krawczyk · 2026-05-30T13:25:07Z

@Croway happy to address any concerns — I don't see the comments on the PR either (and there are none
in the JIRA ticket). Could you re-submit the review? Maybe they were left in a pending/draft state.

Croway · 2026-05-29T08:09:28Z

+
+=== Ollama (local)
+
+Ollama runs models locally and does not require an API key.


Can you add the ollama command to install and run llama3.2, as in the example route? and a link to the ollama website?

Croway · 2026-05-29T08:09:54Z

+
+=== LM Studio (local)
+
+LM Studio serves the model currently loaded in the app. Set `model` to the identifier shown in its UI.


Please add a link to LM Studio website/documentation

Croway · 2026-05-29T08:11:39Z

+    .to("openai:chat-completion?baseUrl=http://localhost:1234/v1&model=local-model");
+----
+
+=== vLLM (self-hosted)


Can you add the vLLM command to install and run meta-llama/Llama-3.1-8B-Instruct, as in the example route? and a link to the vLLM website?

For example, locally I am using vllm-mlx a lot on mac os, can you mention this as well? For example, this is how I run it on my mac vllm-mlx serve mlx-community/Qwen3.6-35B-A3B-4bit --port 8000

Croway · 2026-05-29T08:13:31Z

+
+If vLLM was started with `--api-key`, pass the same value via the `apiKey` option.
+
+=== OpenRouter


Did you manage to actually test it with openrouter? To be honest, when I opened the jira issue, I never used openrouter, I just supposed it would work :D if you have openrouter, and can do a quick test would be nice, otherwise, no worries, maybe @orpiske can test and review the docs (if needed) in the future

…ders Add an "OpenAI-Compatible Providers" section to the OpenAI component docs with baseUrl-based configuration examples for OpenRouter, Ollama, LM Studio, and vLLM, so users discover that no separate component is needed. For OpenRouter, document selecting models via cross-provider identifiers and controlling provider routing/fallbacks through additionalBodyProperty (a JSON body value). Note that OpenRouter's optional HTTP-Referer/X-Title attribution headers cannot be set today, since the component does not expose custom HTTP request headers.

Per review on PR apache#23614: - Ollama: link to ollama.com and the "ollama run llama3.2" command - LM Studio: link to lmstudio.ai - vLLM: link to docs.vllm.ai, "pip install vllm" + "vllm serve" command, plus a note on the vllm-mlx variant for Apple Silicon with an example command

k-krawczyk · 2026-05-30T18:19:47Z

Thanks @Croway — all four addressed:

Ollama — added the ollama run llama3.2 command and a link to https://ollama.com.
LM Studio — added a link to https://lmstudio.ai.
vLLM — added pip install vllm and the vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000
command plus a link to docs.vllm.ai. Also added a note on the vllm-mlx variant for Apple Silicon with
an example vllm-mlx serve mlx-community/Qwen2.5-7B-Instruct-4bit --port 8000.
OpenRouter — honest answer: I didn't test against the live OpenRouter API (no account/key at hand).
The example follows OpenRouter's documented OpenAI-compatible endpoint, and I confirmed in the
producer code (applyAdditionalBodyProperties / parseJsonOrString) that additionalBodyProperty parses
JSON-string values into a real JSON object on the request body, so the nested provider field should
reach OpenRouter correctly. Happy to revise if @orpiske (or anyone with an account) can validate
end-to-end — or I can sign up and re-test if you'd prefer that before merge.

davsclaus

Nice documentation addition — the examples are clear and the honest note about the HTTP header limitation is helpful.

One structural concern: the doc already has two sections covering similar ground that should be consolidated with this new content:

Line 259 — === Using Third-Party or Local OpenAI-Compatible Endpoint shows an LM Studio example at localhost:1234/v1, nearly identical to the new LM Studio example in this PR.
Line 495 — == Compatibility lists the same providers (OpenAI, Ollama, LM Studio, third-party) that the new section now covers in detail.

With the new section in place, these existing sections become redundant. Could you either remove/consolidate them into the new section, or at least add cross-references so readers aren't presented with three overlapping sections?

This review covers project conventions and documentation structure. It does not replace specialized review tools such as CodeRabbit, Sourcery, or SonarCloud.

This review was generated by an AI agent and may contain inaccuracies. Please verify all suggestions before applying.

davsclaus · 2026-05-30T20:11:07Z


+== OpenAI-Compatible Providers
+
+Because the component speaks the OpenAI API, you do not need a separate component to use third-party


This new section overlaps with the existing == Compatibility section further down (currently at line 495 on main), which lists the same providers. It also overlaps with === Using Third-Party or Local OpenAI-Compatible Endpoint (line 259 on main) which has a near-identical LM Studio example.

Now that this comprehensive section exists, consider:

Removing the brief === Using Third-Party or Local OpenAI-Compatible Endpoint section (line 259) since it's now a subset of this content

Trimming the == Compatibility section to avoid repeating the provider list, or merging it into this section

Thanks for catching the overlap. Pushed 2264fbd which:

Removes === Using Third-Party or Local OpenAI-Compatible Endpoint (was line 259); its example is now covered by === LM Studio (local) in the new section.

Removes the == Compatibility heading along with its intro paragraph, bullet list, and NOTE block (redundant with the new provider table).

Preserves the caveat about provider variations from the old == Compatibility NOTE as a NOTE: in the intro of == OpenAI-Compatible Providers.

Promotes === Embedding Models by Provider to sit under == OpenAI-Compatible Providers, right before == Embeddings Operation, so all provider info stays grouped.

Net: -24/+3 lines, single source of truth for OpenAI-compatible provider docs.

Reported by Claude Code on behalf of Karol Krawczyk

…review feedback

gnodet approved these changes May 28, 2026

View reviewed changes

davsclaus approved these changes May 29, 2026

View reviewed changes

github-actions Bot added components docs components-ai labels May 29, 2026

Croway reviewed May 30, 2026

View reviewed changes

k-krawczyk added 2 commits May 30, 2026 20:07

k-krawczyk force-pushed the CAMEL-23500-document-openai-compatible-providers branch from 5486065 to 3062455 Compare May 30, 2026 18:12

davsclaus reviewed May 30, 2026

View reviewed changes

CAMEL-23500: Remove duplicate Compatibility/Third-Party sections per …

2264fbd

…review feedback


		=== Ollama (local)

		Ollama runs models locally and does not require an API key.


		=== LM Studio (local)

		LM Studio serves the model currently loaded in the app. Set `model` to the identifier shown in its UI.


		If vLLM was started with `--api-key`, pass the same value via the `apiKey` option.

		=== OpenRouter


		== OpenAI-Compatible Providers

		Because the component speaks the OpenAI API, you do not need a separate component to use third-party

Conversation

k-krawczyk commented May 28, 2026

Summary

Changes

On the OpenRouter attribution headers

On a dedicated OpenRouter kamelet

Uh oh!

gnodet left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented May 29, 2026

Uh oh!

github-actions Bot commented May 29, 2026

Uh oh!

Croway commented May 29, 2026

Uh oh!

davsclaus commented May 30, 2026

Uh oh!

Croway commented May 30, 2026

Uh oh!

k-krawczyk commented May 30, 2026

Uh oh!

Croway May 29, 2026

Choose a reason for hiding this comment

Uh oh!

Croway May 29, 2026

Choose a reason for hiding this comment

Uh oh!

Croway May 29, 2026

Choose a reason for hiding this comment

Uh oh!

Croway May 29, 2026

Choose a reason for hiding this comment

Uh oh!

k-krawczyk commented May 30, 2026

Uh oh!

davsclaus left a comment

Choose a reason for hiding this comment

Uh oh!

davsclaus May 30, 2026

Choose a reason for hiding this comment

Uh oh!

k-krawczyk May 30, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants