feat(openai): 完善 Chat 与 Responses 参数转发

原生 Chat/Responses 改为透明转发，保留标准工具结构并保护调用方显式参数。补齐 Responses 到 Chat 的兼容转换、协议路由边界、完整响应和流式事件，并同步更新 Swagger、回归测试与真实验收脚本。验证： - cd apps/api && env -u AI_GATEWAY_TEST_DATABASE_URL go test ./... -count=1 - pnpm openapi - pnpm lint - pnpm test - pnpm build - gofmt -l 无输出 - git diff --check 通过风险： - Chat 回退无法等价表达的 Responses 原生能力现在会返回 unsupported_response_parameter - 真实供应商 E2E 因本地没有已启用的平台模型候选而未完成
2026-08-04 19:26:48 +08:00
parent b2c9b4f6d9
commit fe8dcb40ca
22 changed files with 2098 additions and 309 deletions
@@ -74,7 +74,7 @@ func TestOpenAIResponsesChatFallbackPreservesHistoryToolsUsageAndReasoningIntern
 		if len(messages) != 4 {
 			t.Fatalf("expected prior user/assistant plus current system/user/tool messages, got %+v", messages)
 		}
-		if body["max_tokens"] != float64(128) || body["reasoning_effort"] != "high" {
+		if body["max_completion_tokens"] != float64(128) || body["reasoning_effort"] != "high" {
 			t.Fatalf("expected mapped max/reasoning fields: %+v", body)
 		}
 		tools, _ := body["tools"].([]any)
@@ -165,6 +165,27 @@ func TestOpenAIResponsesNativeStreamForwardsEventsWithoutChatAggregation(t *test
 	}
 }

+func TestOpenAIResponsesNativeStreamAcceptsIncompleteTerminalEvent(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "text/event-stream")
+		_, _ = w.Write([]byte("event: response.incomplete\ndata: {\"type\":\"response.incomplete\",\"response\":{\"id\":\"resp_incomplete\",\"object\":\"response\",\"status\":\"incomplete\",\"output\":[],\"incomplete_details\":{\"reason\":\"max_output_tokens\"}}}\n\n"))
+	}))
+	defer server.Close()
+	events := make([]StreamDeltaEvent, 0, 1)
+	response, err := (OpenAIClient{}).Run(context.Background(), Request{
+		Kind: "responses", Model: "Demo", Body: map[string]any{"input": "hello", "stream": true}, Stream: true,
+		Candidate:        store.RuntimeModelCandidate{BaseURL: server.URL, ProviderModelName: "demo", Credentials: map[string]any{"apiKey": "secret"}},
+		UpstreamProtocol: ProtocolOpenAIResponses,
+		StreamDelta:      func(event StreamDeltaEvent) error { events = append(events, event); return nil },
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(events) != 1 || events[0].Event["type"] != "response.incomplete" || response.Result["status"] != "incomplete" || response.UpstreamResponseID != "resp_incomplete" {
+		t.Fatalf("native incomplete terminal event was not preserved: response=%+v events=%+v", response, events)
+	}
+}
+
 func TestOpenAIResponsesChatFallbackStreamsFunctionArgumentFragments(t *testing.T) {
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if r.URL.Path != "/chat/completions" {
@@ -220,6 +241,54 @@ func TestOpenAIResponsesChatFallbackStreamsFunctionArgumentFragments(t *testing.
 	}
 }

+func TestOpenAIResponsesChatFallbackStreamsCustomRefusalAndLogprobsEndToEnd(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "text/event-stream")
+		_, _ = w.Write([]byte("data: {\"id\":\"chatcmpl-custom\",\"object\":\"chat.completion.chunk\",\"model\":\"demo\",\"choices\":[{\"index\":0,\"delta\":{\"role\":\"assistant\",\"content\":\"hi\",\"refusal\":\"no\",\"annotations\":[{\"type\":\"url_citation\"}],\"tool_calls\":[{\"index\":0,\"id\":\"call_custom\",\"type\":\"custom\",\"custom\":{\"name\":\"shell\",\"input\":\"pw\"}}]},\"logprobs\":{\"content\":[{\"token\":\"hi\",\"logprob\":-0.1}]},\"finish_reason\":null}]}\n\n"))
+		_, _ = w.Write([]byte("data: {\"id\":\"chatcmpl-custom\",\"object\":\"chat.completion.chunk\",\"model\":\"demo\",\"choices\":[{\"index\":0,\"delta\":{\"tool_calls\":[{\"index\":0,\"type\":\"custom\",\"custom\":{\"input\":\"d\"}}]},\"finish_reason\":\"tool_calls\"}],\"usage\":{\"prompt_tokens\":2,\"completion_tokens\":3,\"total_tokens\":5}}\n\n"))
+		_, _ = w.Write([]byte("data: [DONE]\n\n"))
+	}))
+	defer server.Close()
+
+	events := make([]StreamDeltaEvent, 0)
+	response, err := (OpenAIClient{}).Run(context.Background(), Request{
+		Kind: "responses", Model: "Demo", Body: map[string]any{
+			"input": "call it", "stream": true, "include": []any{"message.output_text.logprobs"},
+			"tools": []any{map[string]any{"type": "custom", "name": "shell", "format": map[string]any{"type": "text"}}},
+		}, Stream: true,
+		Candidate:        store.RuntimeModelCandidate{BaseURL: server.URL, ProviderModelName: "demo", Credentials: map[string]any{"apiKey": "secret"}},
+		UpstreamProtocol: ProtocolOpenAIChatCompletions, PublicResponseID: "resp_12345678901234567890123456789012",
+		StreamDelta: func(event StreamDeltaEvent) error { events = append(events, event); return nil },
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	output, _ := response.Result["output"].([]any)
+	if len(output) != 2 {
+		t.Fatalf("expected message and custom tool call: %+v", response.Result)
+	}
+	message, _ := output[0].(map[string]any)
+	parts, _ := message["content"].([]any)
+	text, _ := parts[0].(map[string]any)
+	refusal, _ := parts[1].(map[string]any)
+	custom, _ := output[1].(map[string]any)
+	if custom["type"] != "custom_tool_call" || custom["call_id"] != "call_custom" || custom["input"] != "pwd" {
+		t.Fatalf("custom tool stream was not aggregated: %+v", output)
+	}
+	if refusal["refusal"] != "no" || len(text["logprobs"].([]any)) != 1 || len(text["annotations"].([]any)) != 1 {
+		t.Fatalf("refusal/logprobs were not aggregated: %+v", message)
+	}
+	types := make([]string, 0, len(events))
+	for _, event := range events {
+		types = append(types, stringFromAny(event.Event["type"]))
+	}
+	for _, required := range []string{"response.custom_tool_call_input.delta", "response.custom_tool_call_input.done", "response.refusal.delta", "response.refusal.done", "response.completed"} {
+		if !containsTestString(types, required) {
+			t.Fatalf("missing %s in converted stream: %v", required, types)
+		}
+	}
+}
+
 func TestChatResultToResponseMapsIncompleteFinishReason(t *testing.T) {
 	response := ChatResultToResponse(map[string]any{
 		"choices": []any{map[string]any{"finish_reason": "length", "message": map[string]any{"role": "assistant", "content": "partial"}}},
@@ -233,6 +302,23 @@ func TestChatResultToResponseMapsIncompleteFinishReason(t *testing.T) {
 	}
 }

+func TestChatResultToResponseConvertsLegacyFunctionCall(t *testing.T) {
+	response := ChatResultToResponse(map[string]any{
+		"choices": []any{map[string]any{"finish_reason": "function_call", "message": map[string]any{
+			"role": "assistant", "content": nil,
+			"function_call": map[string]any{"name": "legacy_lookup", "arguments": "{\"city\":\"Paris\"}"},
+		}}},
+	}, "resp_12345678901234567890123456789012", "demo", map[string]any{})
+	output, _ := response["output"].([]any)
+	if len(output) != 1 {
+		t.Fatalf("legacy function_call was lost: %+v", response)
+	}
+	call, _ := output[0].(map[string]any)
+	if call["type"] != "function_call" || call["name"] != "legacy_lookup" || call["arguments"] != "{\"city\":\"Paris\"}" {
+		t.Fatalf("legacy function_call was not converted: %+v", call)
+	}
+}
+
 func TestNativeResponsesStreamSupportsMultilineDataFrames(t *testing.T) {
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
 		w.Header().Set("Content-Type", "text/event-stream")
@@ -277,6 +363,7 @@ func TestChatResponsesStreamAdapterEmitsTextItemLifecycle(t *testing.T) {
 	want := []string{
 		"response.created", "response.in_progress", "response.output_item.added", "response.content_part.added",
 		"response.output_text.delta", "response.output_text.done", "response.content_part.done", "response.output_item.done",
+		"response.completed",
 	}
 	if strings.Join(events, ",") != strings.Join(want, ",") {
 		t.Fatalf("unexpected text event lifecycle got=%v want=%v", events, want)
@@ -285,8 +372,8 @@ func TestChatResponsesStreamAdapterEmitsTextItemLifecycle(t *testing.T) {

 func TestResponsesChatFallbackRejectsBuiltInToolsAndUnknownParameters(t *testing.T) {
 	_, err := ResponsesRequestToChat(map[string]any{"input": "hello", "tools": []any{map[string]any{"type": "web_search_preview"}}}, nil)
-	if ErrorCode(err) != "unsupported_response_tool" {
-		t.Fatalf("expected unsupported_response_tool, got %v", err)
+	if ErrorCode(err) != "unsupported_response_parameter" || ErrorParam(err) != "tools[0].type" {
+		t.Fatalf("expected precise unsupported_response_parameter, got %v param=%q", err, ErrorParam(err))
 	}
 	_, err = ResponsesRequestToChat(map[string]any{"input": "hello", "conversation": "conv_1"}, nil)
 	if ErrorCode(err) != "unsupported_response_parameter" {
@@ -317,6 +404,223 @@ func TestResponsesChatFallbackKeepsClientManagedStateAuthoritative(t *testing.T)
 	}
 }

+func TestResponsesChatFallbackMapsMultimodalCustomToolsAndCallHistory(t *testing.T) {
+	body, err := ResponsesRequestToChat(map[string]any{
+		"input": []any{
+			map[string]any{"type": "message", "role": "user", "content": []any{
+				map[string]any{"type": "input_text", "text": "hello", "prompt_cache_breakpoint": map[string]any{"type": "ephemeral"}},
+				map[string]any{"type": "input_image", "image_url": "https://example.com/a.png", "detail": "high"},
+				map[string]any{"type": "input_file", "file_id": "file_1", "filename": "a.pdf"},
+				map[string]any{"type": "input_audio", "input_audio": map[string]any{"data": "AAAA", "format": "wav"}},
+			}},
+			map[string]any{"type": "function_call", "call_id": "call_fn", "name": "lookup", "arguments": "{\"x\":1}"},
+			map[string]any{"type": "function_call_output", "call_id": "call_fn", "output": map[string]any{"ok": true}},
+			map[string]any{"type": "custom_tool_call", "call_id": "call_custom", "name": "shell", "input": "pwd"},
+			map[string]any{"type": "custom_tool_call_output", "call_id": "call_custom", "output": "done"},
+		},
+		"tools": []any{
+			map[string]any{"type": "function", "name": "lookup", "parameters": map[string]any{"type": "object"}, "strict": true},
+			map[string]any{"type": "custom", "name": "shell", "description": "run", "format": map[string]any{"type": "text"}},
+		},
+		"tool_choice": map[string]any{"type": "custom", "name": "shell"},
+		"include":     []any{"message.output_text.logprobs"}, "max_output_tokens": 256,
+	}, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if body["max_completion_tokens"] != 256 || body["logprobs"] != true {
+		t.Fatalf("token/logprobs mapping is incomplete: %+v", body)
+	}
+	messages, _ := body["messages"].([]any)
+	if len(messages) != 5 {
+		t.Fatalf("call history conversion changed item ownership: %+v", messages)
+	}
+	first, _ := messages[0].(map[string]any)
+	parts, _ := first["content"].([]any)
+	if len(parts) != 4 {
+		t.Fatalf("multimodal content was dropped: %+v", parts)
+	}
+	text, _ := parts[0].(map[string]any)
+	image, _ := parts[1].(map[string]any)
+	imageURL, _ := image["image_url"].(map[string]any)
+	file, _ := parts[2].(map[string]any)
+	fileValue, _ := file["file"].(map[string]any)
+	if text["prompt_cache_breakpoint"] == nil || imageURL["detail"] != "high" || fileValue["file_id"] != "file_1" || fileValue["filename"] != "a.pdf" {
+		t.Fatalf("multimodal nested fields changed: %+v", parts)
+	}
+	customMessage, _ := messages[3].(map[string]any)
+	customCalls, _ := customMessage["tool_calls"].([]any)
+	customCall, _ := customCalls[0].(map[string]any)
+	custom, _ := customCall["custom"].(map[string]any)
+	if customCall["type"] != "custom" || custom["name"] != "shell" || custom["input"] != "pwd" {
+		t.Fatalf("custom call history changed: %+v", customMessage)
+	}
+	tools, _ := body["tools"].([]any)
+	customTool, _ := tools[1].(map[string]any)
+	if customTool["type"] != "custom" || customTool["custom"] == nil {
+		t.Fatalf("custom tool definition changed: %+v", tools)
+	}
+	choice, _ := body["tool_choice"].(map[string]any)
+	if choice["type"] != "custom" || choice["custom"] == nil {
+		t.Fatalf("custom tool choice changed: %+v", choice)
+	}
+}
+
+func TestResponsesChatFallbackMapsTextToolOutputAndRejectsNativeOnlyToolOutputContent(t *testing.T) {
+	body, err := ResponsesRequestToChat(map[string]any{"input": []any{map[string]any{
+		"type": "function_call_output", "call_id": "call_1", "output": []any{map[string]any{
+			"type": "input_text", "text": "done", "prompt_cache_breakpoint": map[string]any{"mode": "explicit"},
+		}},
+	}}}, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	messages, _ := body["messages"].([]any)
+	message, _ := messages[0].(map[string]any)
+	parts, _ := message["content"].([]any)
+	part, _ := parts[0].(map[string]any)
+	if part["type"] != "text" || part["text"] != "done" || part["prompt_cache_breakpoint"] == nil {
+		t.Fatalf("text tool output was not preserved: %+v", message)
+	}
+
+	err = ValidateResponsesChatFallback(map[string]any{"input": []any{map[string]any{
+		"type": "function_call_output", "call_id": "call_1", "output": []any{map[string]any{
+			"type": "input_image", "image_url": "https://example.com/a.png", "detail": "high",
+		}},
+	}}})
+	if ErrorCode(err) != "unsupported_response_parameter" || ErrorParam(err) != "input[0].output[0].type" {
+		t.Fatalf("native-only tool output must be rejected precisely, got %v param=%q", err, ErrorParam(err))
+	}
+}
+
+func TestResponsesChatFallbackAcceptsOnlyNoopNativeFields(t *testing.T) {
+	if err := ValidateResponsesChatFallback(map[string]any{
+		"input": "hello", "background": false, "context_management": map[string]any{}, "conversation": "",
+		"prompt": nil, "truncation": "disabled", "reasoning": map[string]any{"summary": nil},
+	}); err != nil {
+		t.Fatalf("no-op native fields should be accepted: %v", err)
+	}
+	for param, value := range map[string]any{
+		"background": true, "conversation": "conv_1", "max_tool_calls": 2, "prompt": map[string]any{"id": "pmpt_1"}, "truncation": "auto",
+	} {
+		err := ValidateResponsesChatFallback(map[string]any{"input": "hello", param: value})
+		if ErrorCode(err) != "unsupported_response_parameter" || ErrorParam(err) != param {
+			t.Fatalf("expected precise rejection for %s, got %v param=%q", param, err, ErrorParam(err))
+		}
+	}
+	err := ValidateResponsesChatFallback(map[string]any{"input": []any{map[string]any{
+		"type": "custom_tool_call", "call_id": "call_1", "name": "tool", "input": "x", "namespace": "native-only",
+	}}})
+	if ErrorCode(err) != "unsupported_response_parameter" || ErrorParam(err) != "input[0].namespace" {
+		t.Fatalf("custom call namespace must be rejected precisely, got %v param=%q", err, ErrorParam(err))
+	}
+}
+
+func TestChatResultToResponseBuildsCompleteResponseWithRefusalLogprobsAndCustomTool(t *testing.T) {
+	request := map[string]any{
+		"background": false, "conversation": nil, "instructions": "be concise", "max_output_tokens": 300,
+		"max_tool_calls": nil, "metadata": map[string]any{"trace": "1"}, "moderation": map[string]any{"type": "auto"},
+		"parallel_tool_calls": true, "previous_response_id": "resp_parent", "prompt": nil, "prompt_cache_key": "cache",
+		"prompt_cache_options": map[string]any{"type": "ephemeral"}, "prompt_cache_retention": "in_memory",
+		"reasoning": map[string]any{"effort": "low"}, "safety_identifier": "safe", "service_tier": "default",
+		"temperature": 0.4, "text": map[string]any{"verbosity": "low"}, "tool_choice": "auto", "tools": []any{},
+		"top_logprobs": 2, "top_p": 0.9, "truncation": "disabled", "user": "user-1",
+	}
+	response := ChatResultToResponse(map[string]any{
+		"created": 1710000000, "service_tier": "priority", "moderation": map[string]any{"flagged": false},
+		"choices": []any{map[string]any{
+			"finish_reason": "stop", "logprobs": map[string]any{"content": []any{map[string]any{"token": "hello", "logprob": -0.1}}},
+			"message": map[string]any{
+				"role": "assistant", "content": "hello", "refusal": "cannot continue", "annotations": []any{map[string]any{"type": "url_citation"}},
+				"tool_calls": []any{
+					map[string]any{"id": "call_fn", "type": "function", "function": map[string]any{"name": "lookup", "arguments": "{\"x\":1}"}},
+					map[string]any{"id": "call_custom", "type": "custom", "custom": map[string]any{"name": "shell", "input": "pwd"}},
+				},
+			},
+		}},
+		"usage": map[string]any{"prompt_tokens": 2, "completion_tokens": 3, "total_tokens": 5},
+	}, "resp_12345678901234567890123456789012", "demo", request)
+	for _, key := range []string{
+		"id", "object", "created_at", "status", "completed_at", "error", "incomplete_details", "instructions", "metadata", "model", "output",
+		"parallel_tool_calls", "temperature", "tool_choice", "tools", "top_p", "background", "conversation", "max_output_tokens", "max_tool_calls",
+		"moderation", "output_text", "previous_response_id", "prompt", "prompt_cache_key", "prompt_cache_options", "prompt_cache_retention", "reasoning",
+		"safety_identifier", "service_tier", "text", "top_logprobs", "truncation", "usage", "user",
+	} {
+		if _, ok := response[key]; !ok {
+			t.Fatalf("complete fallback Response omitted %q: %+v", key, response)
+		}
+	}
+	output, _ := response["output"].([]any)
+	if len(output) != 3 {
+		t.Fatalf("expected message, function, and custom output items: %+v", output)
+	}
+	message, _ := output[0].(map[string]any)
+	parts, _ := message["content"].([]any)
+	text, _ := parts[0].(map[string]any)
+	refusal, _ := parts[1].(map[string]any)
+	custom, _ := output[2].(map[string]any)
+	if len(text["logprobs"].([]any)) != 1 || len(text["annotations"].([]any)) != 1 || refusal["type"] != "refusal" || custom["type"] != "custom_tool_call" || custom["input"] != "pwd" {
+		t.Fatalf("Response content/tool details changed: %+v", output)
+	}
+	if response["service_tier"] != "priority" {
+		t.Fatalf("upstream response service tier was not preserved: %+v", response)
+	}
+}
+
+func TestChatResponsesStreamAdapterEmitsRefusalLogprobsAndCustomToolLifecycle(t *testing.T) {
+	adapter := newChatResponsesStreamAdapter("resp_12345678901234567890123456789012", "demo")
+	events := make([]map[string]any, 0)
+	onDelta := func(event StreamDeltaEvent) error {
+		events = append(events, event.Event)
+		return nil
+	}
+	if err := adapter.delta(StreamDeltaEvent{Event: map[string]any{"choices": []any{map[string]any{
+		"logprobs": map[string]any{"content": []any{map[string]any{"token": "hi", "logprob": -0.1}}},
+		"delta": map[string]any{
+			"content": "hi", "refusal": "no",
+			"tool_calls": []any{map[string]any{"index": 0, "id": "call_custom", "type": "custom", "custom": map[string]any{"name": "shell", "input": "pw"}}},
+		},
+	}}}}, onDelta); err != nil {
+		t.Fatal(err)
+	}
+	if err := adapter.delta(StreamDeltaEvent{Event: map[string]any{"choices": []any{map[string]any{
+		"delta": map[string]any{"tool_calls": []any{map[string]any{"index": 0, "type": "custom", "custom": map[string]any{"input": "d"}}}},
+	}}}}, onDelta); err != nil {
+		t.Fatal(err)
+	}
+	result := ChatResultToResponse(map[string]any{"choices": []any{map[string]any{
+		"message": map[string]any{"role": "assistant", "content": "hi", "refusal": "no", "tool_calls": []any{
+			map[string]any{"id": "call_custom", "type": "custom", "custom": map[string]any{"name": "shell", "input": "pwd"}},
+		}},
+	}}}, adapter.publicID, "demo", map[string]any{})
+	if err := adapter.done(result, onDelta); err != nil {
+		t.Fatal(err)
+	}
+	types := make([]string, 0, len(events))
+	var sawLogprobs bool
+	for index, event := range events {
+		types = append(types, stringFromAny(event["type"]))
+		if intFromAny(event["sequence_number"]) != index {
+			t.Fatalf("non-contiguous sequence at %d: %+v", index, event)
+		}
+		if event["type"] == "response.output_text.delta" {
+			logprobs, _ := event["logprobs"].([]any)
+			sawLogprobs = len(logprobs) == 1
+		}
+	}
+	for _, required := range []string{
+		"response.refusal.delta", "response.refusal.done", "response.custom_tool_call_input.delta",
+		"response.custom_tool_call_input.done", "response.output_item.done", "response.completed",
+	} {
+		if !containsTestString(types, required) {
+			t.Fatalf("missing %s lifecycle event: %v", required, types)
+		}
+	}
+	if !sawLogprobs {
+		t.Fatalf("streamed output_text delta lost logprobs: %+v", events)
+	}
+}
+
 func mustJSON(t *testing.T, value any) []byte {
 	t.Helper()
 	data, err := json.Marshal(value)