fix(embedding): remove forced /v1 suffix for embeddings

[ccsang]

Fixes #6558

Problem

AstrBot's embedding adapter unconditionally appends /v1 to all API base URLs.

Solution

Add embedding_api_base_mode config option (auto|force_v1|as_is).

Testing

• ✅ All 7 new tests pass

Co-Authored-By: Claude Sonnet 4.6 noreply@anthropic.com

Summary by Sourcery

Make OpenAI-compatible embedding providers use a shared helper to resolve the API base URL and support configurable handling of the /v1 suffix.

New Features:

• Add a configurable embedding_api_base_mode option (auto|force_v1|as_is) to control how /v1 is appended to embedding API base URLs.

Bug Fixes:

• Prevent embedding API base URLs from being incorrectly forced to end with /v1 when a different path is required.

Enhancements:

• Introduce a reusable resolve_openai_compatible_base_url utility for consistent base URL handling across providers.

Tests:

• Add unit and async tests covering resolve_openai_compatible_base_url behavior and embedding provider base URL resolution for all modes and edge cases.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request resolves an issue where AstrBot's embedding adapter rigidly appended /v1 to all API base URLs, limiting compatibility with diverse OpenAI-compatible services. By introducing a configurable embedding_api_base_mode and a dedicated URL resolution utility, the system now offers flexible control over API endpoint formatting, enhancing adaptability and user experience for embedding providers.

Highlights

• Flexible API Base URL Handling: Introduced a new configuration option embedding_api_base_mode with auto, force_v1, and as_is settings to control how the /v1 suffix is handled for embedding API base URLs.
• Centralized URL Resolution Logic: Implemented a resolve_openai_compatible_base_url utility function to encapsulate and manage the logic for resolving OpenAI-compatible API base URLs based on the chosen mode.
• Refactored Embedding Provider: Updated the OpenAI embedding provider to utilize the new flexible API base URL resolution utility, removing the previous hardcoded and forced /v1 suffix appending logic.
• Comprehensive Testing: Added new unit tests to thoroughly validate the behavior of the resolve_openai_compatible_base_url utility and the updated embedding provider across all supported API base URL modes.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a flexible way to handle the /v1 suffix for embedding provider API base URLs by adding a new embedding_api_base_mode configuration. The implementation correctly centralizes the URL resolution logic into a new utility function and adds comprehensive tests. My review includes a suggestion to refactor some duplicated code in the new utility for better maintainability, and a fix for an incorrect assertion in one of the new tests to ensure the test suite is accurate.

[sourcery-ai]

Hey - I've found 2 issues, and left some high level feedback:

• Consider adding explicit runtime validation or normalization for embedding_api_base_mode values (e.g., mapping unknown strings to auto with a warning) so that typos in configuration don’t silently change behavior.
• The logic for force_v1 and auto in resolve_openai_compatible_base_url is very similar; you could simplify by factoring out the shared /v1-ensuring behavior into a common path and only branching where behavior truly differs.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- Consider adding explicit runtime validation or normalization for `embedding_api_base_mode` values (e.g., mapping unknown strings to `auto` with a warning) so that typos in configuration don’t silently change behavior.
- The logic for `force_v1` and `auto` in `resolve_openai_compatible_base_url` is very similar; you could simplify by factoring out the shared `/v1`-ensuring behavior into a common path and only branching where behavior truly differs.

## Individual Comments

### Comment 1
<location path="astrbot/core/provider/utils.py" line_range="26-27" />
<code_context>
+    if not api_base:
+        return default_base
+
+    if mode == "as_is":
+        return api_base.removesuffix("/")
+
+    if mode == "force_v1":
</code_context>
<issue_to_address>
**issue (bug_risk):** "as_is" mode still normalizes the URL by stripping the trailing slash

This currently contradicts the docstring promise of returning the URL “as-is”. Please either (a) update the docstring to clarify that trailing slashes are removed, or (b) return `api_base` unchanged in `as_is` (skipping `removesuffix('/')`) so behavior matches the documentation and caller expectations.
</issue_to_address>

### Comment 2
<location path="astrbot/core/config/default.py" line_range="1941-1945" />
<code_context>
                         "description": "API Base URL",
                         "type": "string",
                     },
+                    "embedding_api_base_mode": {
+                        "description": "API Base URL Mode",
+                        "type": "string",
+                        "hint": "控制 API Base URL 的 /v1 后缀处理方式。auto: 自动判断（默认），如果 URL 不以 /v1 结尾则添加。force_v1: 强制添加 /v1 后缀。as_is: 保持原样不做修改。",
+                    },
                     "volcengine_cluster": {
</code_context>
<issue_to_address>
**suggestion:** Consider constraining `embedding_api_base_mode` to a fixed set of allowed values

The schema currently treats `embedding_api_base_mode` as a free-form string, but the implementation only supports `"auto" | "force_v1" | "as_is"`. If the config system supports enums (or equivalent), restricting this field to those values would better match runtime behavior and avoid misconfiguration.

```suggestion
                    "embedding_api_base_mode": {
                        "description": "API Base URL Mode",
                        "type": "string",
                        "enum": ["auto", "force_v1", "as_is"],
                        "hint": "控制 API Base URL 的 /v1 后缀处理方式。auto: 自动判断（默认），如果 URL 不以 /v1 结尾则添加。force_v1: 强制添加 /v1 后缀。as_is: 保持原样不做修改。",
                    },
```
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fa22ca83f1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Soulter]

#6669 fixed