Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
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.mdindex 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.mdindex 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.pyindex 9abb42c47..54b4a6d9c 100644--- a/openviking_gateway/models.py+++ b/openviking_gateway/models.py@@ -88,6 +88,7 @@ class Upstream(BaseModel):name: strprotocol: ProtocolNamebase_url: str+ append_endpoint_path: bool = Trueapi_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.pyindex 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 baseif upstream["protocol"] != "anthropic":path = path.removeprefix("/v1")return base + pathdiff --git a/tests/gateway/test_upstream_urls.py b/tests/gateway/test_upstream_urls.pyindex 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.tsindex 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.tsindex 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.tsxindex 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.tsxindex 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><SettingSectiondiff --git a/web-studio/src/routes/gateway/-components/upstreams-pages.test.tsx b/web-studio/src/routes/gateway/-components/upstreams-pages.test.tsxindex 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.tsindex 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: stringprotocol: Protocolbase_url: string+ /** Append the selected protocol's endpoint path to base_url. */+ append_endpoint_path: booleanauth_mode: AuthModemodels: 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.tsindex 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.tsindex 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 basereturn (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 undefinedconst 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,+ )}/**