Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(gateway): allow exact upstream endpoint URLs (#6100)

Caucher Wang9baf83f04ce0
diff --git a/docs/en/guides/22-gateway-operations.md b/docs/en/guides/22-gateway-operations.md
index b39d7eb1d..cbd8afe13 100644
--- a/docs/en/guides/22-gateway-operations.md
+++ b/docs/en/guides/22-gateway-operations.md
@@ -248,6 +248,7 @@ When you choose a provider in the editor, its default Base URL is filled in:
- A trailing slash is removed. Addresses with a version path, such as `/api/paas/v4`, work as is.
- Requests that clients send to the Ark paths (`/gateway/api/v3/`, `/gateway/api/compatible/v1/`) follow the same rules.
- An upstream has one Base URL. If a provider uses different addresses for different protocols, create separate upstreams. For example, Zhipu uses `https://open.bigmodel.cn/api/paas/v4` for Chat Completions and `https://open.bigmodel.cn/api/v1` for Responses. Ark Coding Plan uses `…/api/coding/v3` for Chat Completions and Responses and `…/api/coding` for Anthropic Messages.
+- **Append protocol endpoint path** is on by default. Turn it off when Base URL is already the complete request endpoint; the gateway then sends every upstream request to that exact URL without adding a protocol path.
The editor previews the final request URL as you type. If an OpenAI or Ark address is missing its path, or an Anthropic address ends in `/v1`, it warns you and offers a one-click fix.
@@ -719,6 +720,7 @@ URLs must be HTTP(S) and contain no credentials, query or fragment. Unknown fiel
| Protocol | `protocol` | | `anthropic` (Anthropic Messages), `chat` (Chat Completions) or `responses` (Responses). |
| Provider | `vendor` | `generic` | `generic`, `anthropic`, `openai`, `deepseek`, `ark` (Volcano Engine Ark) or `byteplus` (BytePlus ModelArk). Studio offers only the protocols a provider supports; the API accepts any pair. |
| Base URL | `base_url` | | Provider address; defaults and path rules are in [Upstreams](#upstreams). |
+| Append protocol endpoint path | `append_endpoint_path` | `true` | Appends the selected protocol's path; when false, uses `base_url` as the complete request URL. |
| Who provides the API key | `auth_mode` | `managed` | `managed` (the gateway holds the API key) or `passthrough` (each client sends its own key). |
| API key | `api_key` | | Write-only; see [Credentials](#credentials). |
| Extra headers | `headers` | `{}` | Write-only; see [Credentials](#credentials). |
diff --git a/docs/zh/guides/22-gateway-operations.md b/docs/zh/guides/22-gateway-operations.md
index 11e02db3c..f83698d53 100644
--- a/docs/zh/guides/22-gateway-operations.md
+++ b/docs/zh/guides/22-gateway-operations.md
@@ -248,6 +248,7 @@ ov.example.com {
- 末尾的斜杠会被去掉。`/api/paas/v4` 这类带版本路径的地址可以直接使用。
- 客户端用方舟路径(`/gateway/api/v3/`、`/gateway/api/compatible/v1/`)发来的请求,按同样的规则拼接。
- 一个上游只有一个 Base URL。同一服务商的不同协议地址不同时,要分别建上游:例如智谱 Chat Completions 用 `https://open.bigmodel.cn/api/paas/v4`,Responses 用 `https://open.bigmodel.cn/api/v1`。方舟 Coding Plan 的 Chat Completions 和 Responses 用 `…/api/coding/v3`,Anthropic Messages 用 `…/api/coding`。
+- **拼接协议接口路径**默认开启。如果 Base URL 已经是完整的请求地址,可以关闭它;关闭后,网关的所有上游请求都直接使用该 URL,不再拼接协议路径。
编辑页会实时预览最终的请求地址;OpenAI、方舟这类地址漏掉路径,或者 Anthropic 地址多了 `/v1` 时,会给出提示和一键修正。
@@ -719,6 +720,7 @@ URL 必须是 HTTP(S),不能含凭证、查询参数或 fragment。未知字
| 协议 | `protocol` | | `anthropic`(Anthropic Messages)、`chat`(Chat Completions)或 `responses`(Responses)。 |
| 服务商 | `vendor` | `generic` | `generic`、`anthropic`、`openai`、`deepseek`、`ark`(火山方舟)或 `byteplus`(BytePlus 方舟)。Studio 只提供服务商支持的协议,API 接受任意组合。 |
| Base URL | `base_url` | | 服务商地址;默认地址和拼接规则见[上游](#上游)。 |
+| 拼接协议接口路径 | `append_endpoint_path` | `true` | 拼接所选协议的接口路径;关闭时把 `base_url` 直接作为完整请求地址。 |
| API Key 由谁提供 | `auth_mode` | `managed` | `managed`(由网关保管 API Key)或 `passthrough`(每个客户端自带 API Key)。 |
| API Key | `api_key` | | 只写,见[凭证](#凭证)。 |
| 额外请求头 | `headers` | `{}` | 只写,见[凭证](#凭证)。 |
diff --git a/openviking_gateway/models.py b/openviking_gateway/models.py
index 9abb42c47..54b4a6d9c 100644
--- a/openviking_gateway/models.py
+++ b/openviking_gateway/models.py
@@ -88,6 +88,7 @@ class Upstream(BaseModel):
name: str
protocol: ProtocolName
base_url: str
+ append_endpoint_path: bool = True
api_key: str = ""
auth_mode: Literal["managed", "passthrough"] = "managed"
headers: dict[str, str] = Field(default_factory=dict)
@@ -131,7 +132,11 @@ class Upstream(BaseModel):
@model_validator(mode="after")
def validate_protocol_base(self):
- if self.protocol == "anthropic" and urlsplit(self.base_url).path.endswith("/v1"):
+ if (
+ self.append_endpoint_path
+ and self.protocol == "anthropic"
+ and urlsplit(self.base_url).path.endswith("/v1")
+ ):
raise ValueError(
"Anthropic base_url must not end in /v1; the gateway appends /v1/messages"
)
diff --git a/openviking_gateway/proxy.py b/openviking_gateway/proxy.py
index 2a110ac9f..709893bf7 100644
--- a/openviking_gateway/proxy.py
+++ b/openviking_gateway/proxy.py
@@ -63,6 +63,8 @@ def filtered_headers(headers, request=False):
def upstream_url(upstream, path):
base = upstream["base_url"].rstrip("/")
+ if not upstream.get("append_endpoint_path", True):
+ return base
if upstream["protocol"] != "anthropic":
path = path.removeprefix("/v1")
return base + path
diff --git a/tests/gateway/test_upstream_urls.py b/tests/gateway/test_upstream_urls.py
index 006c6e8f6..437115895 100644
--- a/tests/gateway/test_upstream_urls.py
+++ b/tests/gateway/test_upstream_urls.py
@@ -21,6 +21,23 @@ def test_upstream_url_vectors(vector):
assert upstream_url(upstream, vector["path"]) == vector["expected"]
+ ("protocol", "path"),
+ [
+ ("anthropic", "/v1/messages"),
+ ("chat", "/v1/chat/completions"),
+ ("responses", "/v1/responses"),
+ ],
+)
+def test_upstream_url_can_skip_endpoint_path(protocol, path):
+ upstream = {
+ "protocol": protocol,
+ "base_url": "https://api.example.test/custom/endpoint/",
+ "append_endpoint_path": False,
+ }
+ assert upstream_url(upstream, path) == "https://api.example.test/custom/endpoint"
+
+
@pytest.mark.parametrize("prefix", ["api/v3", "api/compatible/v1", "v1"])
@pytest.mark.parametrize(
"suffix", ["embeddings", "models", "responses/id/cancel", "messages/count_tokens"]
@@ -37,6 +54,18 @@ def test_anthropic_base_rejects_v1_suffix(base):
Upstream(name="test", protocol="anthropic", base_url=base)
+def test_endpoint_path_defaults_on_and_allows_anthropic_v1_when_off():
+ default = Upstream(name="default", protocol="chat", base_url="https://example.test/v1")
+ exact = Upstream(
+ name="exact",
+ protocol="anthropic",
+ base_url="https://example.test/v1",
+ append_endpoint_path=False,
+ )
+ assert default.append_endpoint_path is True
+ assert exact.append_endpoint_path is False
+
+
@pytest.mark.parametrize("protocol", ["chat", "responses", "anthropic"])
def test_upstream_auth_headers(protocol):
headers = upstream_headers(
diff --git a/web-studio/src/i18n/locales/en/gateway/upstreams.ts b/web-studio/src/i18n/locales/en/gateway/upstreams.ts
index 951049a42..f5e3f1a3c 100644
--- a/web-studio/src/i18n/locales/en/gateway/upstreams.ts
+++ b/web-studio/src/i18n/locales/en/gateway/upstreams.ts
@@ -202,6 +202,11 @@ const upstreams = {
correctPath: 'Use {{url}}',
useDefault: 'Use default',
},
+ appendEndpointPath: {
+ label: 'Append protocol endpoint path',
+ description:
+ 'Adds the path for the selected protocol to the Base URL. Turn this off when the Base URL is already the complete request endpoint.',
+ },
authMode: {
label: 'Who provides the API key',
managed: {
diff --git a/web-studio/src/i18n/locales/zh-CN/gateway/upstreams.ts b/web-studio/src/i18n/locales/zh-CN/gateway/upstreams.ts
index bd5cd3d04..20d22b643 100644
--- a/web-studio/src/i18n/locales/zh-CN/gateway/upstreams.ts
+++ b/web-studio/src/i18n/locales/zh-CN/gateway/upstreams.ts
@@ -192,6 +192,11 @@ const upstreams = {
correctPath: '改用 {{url}}',
useDefault: '使用默认地址',
},
+ appendEndpointPath: {
+ label: '拼接协议接口路径',
+ description:
+ '在 Base URL 后拼接所选协议的接口路径。如果 Base URL 已经是完整的请求地址,请关闭此开关。',
+ },
authMode: {
label: 'API Key 由谁提供',
managed: {
diff --git a/web-studio/src/routes/gateway/-components/connect-page.test.tsx b/web-studio/src/routes/gateway/-components/connect-page.test.tsx
index deca14989..bf10116fa 100644
--- a/web-studio/src/routes/gateway/-components/connect-page.test.tsx
+++ b/web-studio/src/routes/gateway/-components/connect-page.test.tsx
@@ -79,6 +79,7 @@ function upstream(overrides: Partial<Upstream>): Upstream {
name: 'Upstream',
protocol: 'chat',
base_url: 'https://api.example.com/v1',
+ append_endpoint_path: true,
auth_mode: 'managed',
models: [],
aliases: {},
diff --git a/web-studio/src/routes/gateway/-components/upstreams-form.tsx b/web-studio/src/routes/gateway/-components/upstreams-form.tsx
index e5ad75aa2..f7bfc6378 100644
--- a/web-studio/src/routes/gateway/-components/upstreams-form.tsx
+++ b/web-studio/src/routes/gateway/-components/upstreams-form.tsx
@@ -382,6 +382,15 @@ export function UpstreamForm({
) : null}
</div>
</SettingField>
+ <ToggleRow
+ id="upstream-append-endpoint-path"
+ label={t('upstreams.form.appendEndpointPath.label')}
+ description={t('upstreams.form.appendEndpointPath.description')}
+ checked={draft.append_endpoint_path}
+ onCheckedChange={(enabled) =>
+ onChange('append_endpoint_path', enabled)
+ }
+ />
</SettingSection>
<SettingSection
diff --git a/web-studio/src/routes/gateway/-components/upstreams-pages.test.tsx b/web-studio/src/routes/gateway/-components/upstreams-pages.test.tsx
index 50c51b2b0..09d54f9be 100644
--- a/web-studio/src/routes/gateway/-components/upstreams-pages.test.tsx
+++ b/web-studio/src/routes/gateway/-components/upstreams-pages.test.tsx
@@ -420,6 +420,23 @@ describe('UpstreamEditor', () => {
)
})
+ it('can send requests to the exact base URL without a protocol path', async () => {
+ renderAt('/gateway/upstreams/u1')
+ await screen.findByLabelText('upstreams.form.name.label')
+ const toggle = screen.getByRole('switch', {
+ name: 'upstreams.form.appendEndpointPath.label',
+ })
+ expect(toggle.getAttribute('aria-checked')).toBe('true')
+
+ fireEvent.click(toggle)
+ expect(toggle.getAttribute('aria-checked')).toBe('false')
+ expect(screen.getByText('https://api.openai.com/v1')).toBeTruthy()
+
+ fireEvent.click(screen.getByRole('button', { name: 'actions.save' }))
+ await waitFor(() => expect(api.saveUpstream).toHaveBeenCalledTimes(1))
+ expect(lastSavedBody().append_endpoint_path).toBe(false)
+ })
+
it('asks for the API key and header values again after the address changes', async () => {
renderAt('/gateway/upstreams/u1')
await screen.findByLabelText('upstreams.form.name.label')
diff --git a/web-studio/src/routes/gateway/-lib/api.ts b/web-studio/src/routes/gateway/-lib/api.ts
index 3957a1aa2..633bdf70c 100644
--- a/web-studio/src/routes/gateway/-lib/api.ts
+++ b/web-studio/src/routes/gateway/-lib/api.ts
@@ -58,6 +58,8 @@ type UpstreamSettings = {
name: string
protocol: Protocol
base_url: string
+ /** Append the selected protocol's endpoint path to base_url. */
+ append_endpoint_path: boolean
auth_mode: AuthMode
models: string[]
/** Name clients use → model sent to the upstream. */
diff --git a/web-studio/src/routes/gateway/-lib/upstream-schema.test.ts b/web-studio/src/routes/gateway/-lib/upstream-schema.test.ts
index f38d07c27..3fed7d216 100644
--- a/web-studio/src/routes/gateway/-lib/upstream-schema.test.ts
+++ b/web-studio/src/routes/gateway/-lib/upstream-schema.test.ts
@@ -182,10 +182,34 @@ describe('base URLs', () => {
},
)
+ it.each([
+ ['anthropic', '/v1/messages'],
+ ['chat', '/v1/chat/completions'],
+ ['responses', '/v1/responses'],
+ ] as const)('can use the exact URL for %s', (protocol, path) => {
+ expect(
+ upstreamUrl(
+ 'https://api.example.com/custom/endpoint/',
+ protocol,
+ path,
+ false,
+ ),
+ ).toBe('https://api.example.com/custom/endpoint')
+ })
+
it('previews the protocol endpoint once the URL is valid', () => {
expect(endpointPreview(input({ protocol: 'responses' }))).toBe(
'https://api.example.com/v1/responses',
)
+ expect(
+ endpointPreview(
+ input({
+ protocol: 'responses',
+ base_url: 'https://api.example.com/custom/endpoint',
+ append_endpoint_path: false,
+ }),
+ ),
+ ).toBe('https://api.example.com/custom/endpoint')
expect(endpointPreview(input({ base_url: 'api.example' }))).toBe('')
})
})
@@ -343,6 +367,9 @@ describe('URL corrections and changed secrets', () => {
expect(validateUpstream(draft).base_url?.key).toBe(
'validation.anthropicBaseUrl',
)
+ const exact = { ...draft, append_endpoint_path: false }
+ expect(baseUrlCorrection(exact)).toBeUndefined()
+ expect(validateUpstream(exact)).toEqual({})
})
it('recognizes address changes but ignores trailing slashes', () => {
expect(baseUrlChanged({ base_url: stored.base_url + '/' }, stored)).toBe(
diff --git a/web-studio/src/routes/gateway/-lib/upstream-schema.ts b/web-studio/src/routes/gateway/-lib/upstream-schema.ts
index eeb8d38ad..b89c3faa6 100644
--- a/web-studio/src/routes/gateway/-lib/upstream-schema.ts
+++ b/web-studio/src/routes/gateway/-lib/upstream-schema.ts
@@ -7,6 +7,7 @@ export const UPSTREAM_DEFAULTS: UpstreamInput = {
name: '',
protocol: 'chat',
base_url: '',
+ append_endpoint_path: true,
api_key: '',
auth_mode: 'managed',
headers: {},
@@ -221,13 +222,15 @@ export function isValidBaseUrl(value: string): boolean {
)
}
-/** SDK URL joining: OpenAI paths omit /v1; Anthropic paths retain it. */
+/** Upstream URL joining: OpenAI paths omit /v1; Anthropic paths retain it. */
export function upstreamUrl(
baseUrl: string,
protocol: Protocol,
path: string,
+ appendEndpointPath = true,
): string {
const base = baseUrl.trim().replace(/\/+$/, '')
+ if (!appendEndpointPath) return base
return (
base + (protocol === 'anthropic' ? path : path.replace(/^\/v1(?=\/)/, ''))
)
@@ -235,9 +238,13 @@ export function upstreamUrl(
/** A likely URL mistake that the editor can fix without replacing a custom host. */
export function baseUrlCorrection(
- upstream: Pick<UpstreamInput, 'base_url' | 'vendor' | 'protocol'>,
+ upstream: Pick<
+ UpstreamInput,
+ 'base_url' | 'vendor' | 'protocol' | 'append_endpoint_path'
+ >,
): { reason: 'anthropicVersion' | 'missingPath'; url: string } | undefined {
- if (!isValidBaseUrl(upstream.base_url)) return undefined
+ if (!upstream.append_endpoint_path || !isValidBaseUrl(upstream.base_url))
+ return undefined
const base = upstream.base_url.trim().replace(/\/+$/, '')
const path = new URL(base).pathname.replace(/\/+$/, '')
if (upstream.protocol === 'anthropic' && path.endsWith('/v1')) {
@@ -271,11 +278,19 @@ export function baseUrlChanged(
* empty while the base URL is not valid yet.
*/
export function endpointPreview(
- upstream: Pick<UpstreamInput, 'base_url' | 'vendor' | 'protocol'>,
+ upstream: Pick<
+ UpstreamInput,
+ 'base_url' | 'vendor' | 'protocol' | 'append_endpoint_path'
+ >,
protocol: Protocol = upstream.protocol,
): string {
if (!isValidBaseUrl(upstream.base_url)) return ''
- return upstreamUrl(upstream.base_url, protocol, PROTOCOL_PATHS[protocol])
+ return upstreamUrl(
+ upstream.base_url,
+ protocol,
+ PROTOCOL_PATHS[protocol],
+ upstream.append_endpoint_path,
+ )
}
/**