Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

fix(go-models): unwrap bundled api_key for Azure OpenAI (#20354)

Denis Ermakov95f3c9e464fc
diff --git a/internal/entity/models/azure_openai.go b/internal/entity/models/azure_openai.go
index 5dc801b82c..3014732942 100644
--- a/internal/entity/models/azure_openai.go
+++ b/internal/entity/models/azure_openai.go
@@ -21,13 +21,59 @@ import (
"encoding/json"
"fmt"
"io"
+ "net/url"
"ragflow/internal/common"
"strings"
)
// azureAPIVersion is the Azure OpenAI REST API version sent as the
+// api-version query parameter when the instance does not configure one.
const azureAPIVersion = "2024-10-21"
+// azureStreamUsageAPIVersion is the first API version that accepts
+// stream_options.include_usage.
+const azureStreamUsageAPIVersion = "2024-09-01"
+
+// azureCredentials extracts the API key and API version from the stored
+// api_key. When an API version is set, the model settings form stores
+// api_key as a JSON object:
+//
+// {"api_key": "...", "api_version": "..."}
+//
+// Otherwise api_key is the plain key and azureAPIVersion applies.
+func azureCredentials(apiConfig *APIConfig) (apiKey, apiVersion string) {
+ if apiConfig == nil || apiConfig.ApiKey == nil {
+ return "", azureAPIVersion
+ }
+ key := strings.TrimSpace(*apiConfig.ApiKey)
+ if strings.HasPrefix(key, "{") {
+ var bundle struct {
+ APIKey string `json:"api_key"`
+ APIVersion string `json:"api_version"`
+ }
+ if err := json.Unmarshal([]byte(key), &bundle); err == nil {
+ apiVersion = strings.TrimSpace(bundle.APIVersion)
+ if apiVersion == "" {
+ apiVersion = azureAPIVersion
+ }
+ return strings.TrimSpace(bundle.APIKey), apiVersion
+ }
+ }
+ return key, azureAPIVersion
+}
+
+// azureSupportsStreamUsage reports whether apiVersion accepts
+// stream_options.include_usage. Dated versions (YYYY-MM-DD, optionally with a
+// -preview suffix) are compared by date; undated ones such as "preview" and
+// "latest" track the newest API.
+func azureSupportsStreamUsage(apiVersion string) bool {
+ const dateLen = len(azureStreamUsageAPIVersion)
+ if len(apiVersion) < dateLen || apiVersion[0] < '0' || apiVersion[0] > '9' {
+ return true
+ }
+ return apiVersion[:dateLen] >= azureStreamUsageAPIVersion
+}
+
// AzureOpenAIModel implements ModelDriver for Azure OpenAI.
type AzureOpenAIModel struct {
baseModel BaseModel
@@ -43,7 +89,8 @@ func NewAzureOpenAIModel(baseURL map[string]string, urlSuffix URLSuffix) *AzureO
// Azure OpenAI authenticates with the non-standard "api-key"
// header instead of "Authorization: Bearer".
authHeader: func(cfg *APIConfig) (string, string) {
- return "api-key", *cfg.ApiKey
+ apiKey, _ := azureCredentials(cfg)
+ return "api-key", apiKey
},
},
}
@@ -57,15 +104,24 @@ func (a *AzureOpenAIModel) Name() string {
return "azure-openai"
}
+// checkAPIConfig rejects a missing API key, including a stored JSON object
+// whose api_key field is empty.
+func (a *AzureOpenAIModel) checkAPIConfig(apiConfig *APIConfig) error {
+ if apiKey, _ := azureCredentials(apiConfig); apiKey == "" {
+ return fmt.Errorf("api key is required")
+ }
+ return nil
+}
+
// deploymentURL builds a deployment-scoped data-plane URL of the form
-func (a *AzureOpenAIModel) deploymentURL(baseURL, deployment, op string) string {
+func (a *AzureOpenAIModel) deploymentURL(baseURL, deployment, op, apiVersion string) string {
return fmt.Sprintf("%s/deployments/%s/%s?api-version=%s",
- strings.TrimRight(baseURL, "/"), deployment, op, azureAPIVersion)
+ strings.TrimRight(baseURL, "/"), deployment, op, url.QueryEscape(apiVersion))
}
// ChatWithMessages sends multiple messages with roles and returns the response.
func (a *AzureOpenAIModel) ChatWithMessages(ctx context.Context, modelName string, messages []Message, apiConfig *APIConfig, chatModelConfig *ChatConfig, modelUsage *common.ModelUsage) (*ChatResponse, error) {
- if err := a.baseModel.APIConfigCheck(apiConfig); err != nil {
+ if err := a.checkAPIConfig(apiConfig); err != nil {
return nil, err
}
@@ -82,7 +138,8 @@ func (a *AzureOpenAIModel) ChatWithMessages(ctx context.Context, modelName strin
return nil, err
}
baseURL = strings.TrimSuffix(baseURL, "/")
- url := a.deploymentURL(baseURL, modelName, a.baseModel.URLSuffix.Chat)
+ _, apiVersion := azureCredentials(apiConfig)
+ url := a.deploymentURL(baseURL, modelName, a.baseModel.URLSuffix.Chat, apiVersion)
// Azure preserves its own body shape (no "model" field; deployment is in
// the URL; temperature defaults to 1) rather than using buildRequestBody
@@ -116,7 +173,7 @@ func (a *AzureOpenAIModel) ChatWithMessages(ctx context.Context, modelName strin
// ChatStreamlyWithSender sends messages and streams the response via the
// sender function. Used for streaming chat responses with no extra channel.
func (a *AzureOpenAIModel) ChatStreamlyWithSender(ctx context.Context, modelName string, messages []Message, apiConfig *APIConfig, chatModelConfig *ChatConfig, modelUsage *common.ModelUsage, sender func(*string, *string) error) error {
- if err := a.baseModel.APIConfigCheck(apiConfig); err != nil {
+ if err := a.checkAPIConfig(apiConfig); err != nil {
return err
}
@@ -137,7 +194,8 @@ func (a *AzureOpenAIModel) ChatStreamlyWithSender(ctx context.Context, modelName
return err
}
baseURL = strings.TrimSuffix(baseURL, "/")
- url := a.deploymentURL(baseURL, modelName, a.baseModel.URLSuffix.Chat)
+ _, apiVersion := azureCredentials(apiConfig)
+ url := a.deploymentURL(baseURL, modelName, a.baseModel.URLSuffix.Chat, apiVersion)
reqBody := map[string]interface{}{
"messages": buildChatMessages(messages),
@@ -161,8 +219,10 @@ func (a *AzureOpenAIModel) ChatStreamlyWithSender(ctx context.Context, modelName
// Request token usage in streaming response. Azure OpenAI only
// includes usage in the final chunk when stream_options.include_usage
- // is set.
- reqBody["stream_options"] = map[string]any{"include_usage": true}
+ // is set, and rejects the option on API versions that predate it.
+ if azureSupportsStreamUsage(apiVersion) {
+ reqBody["stream_options"] = map[string]any{"include_usage": true}
+ }
return a.baseModel.doStreamRequest(ctx, url, apiConfig, reqBody, streamCallTimeout, func(body io.ReadCloser) error {
return HandleStreamingResponse(body, modelUsage, chatModelConfig, OpenAIParserConfig, sender)
@@ -178,7 +238,7 @@ type azureEmbeddingResponse struct {
// Embed turns a list of texts into embedding vectors
func (a *AzureOpenAIModel) Embed(ctx context.Context, modelName *string, request EmbedRequest, apiConfig *APIConfig, embeddingConfig *EmbeddingConfig, modelUsage *common.ModelUsage) ([]EmbeddingData, error) {
- if err := a.baseModel.APIConfigCheck(apiConfig); err != nil {
+ if err := a.checkAPIConfig(apiConfig); err != nil {
return nil, err
}
@@ -195,7 +255,8 @@ func (a *AzureOpenAIModel) Embed(ctx context.Context, modelName *string, request
return nil, err
}
baseURL = strings.TrimSuffix(baseURL, "/")
- url := a.deploymentURL(baseURL, *modelName, a.baseModel.URLSuffix.Embedding)
+ _, apiVersion := azureCredentials(apiConfig)
+ url := a.deploymentURL(baseURL, *modelName, a.baseModel.URLSuffix.Embedding, apiVersion)
// As with chat, the deployment is in the URL path, so no "model" field.
reqBody := map[string]interface{}{
@@ -230,7 +291,7 @@ func (a *AzureOpenAIModel) Embed(ctx context.Context, modelName *string, request
// ListModels returns the deployment names visible to the configured API key.
func (a *AzureOpenAIModel) ListModels(ctx context.Context, apiConfig *APIConfig) ([]ListModelResponse, error) {
- if err := a.baseModel.APIConfigCheck(apiConfig); err != nil {
+ if err := a.checkAPIConfig(apiConfig); err != nil {
return nil, err
}
@@ -238,7 +299,8 @@ func (a *AzureOpenAIModel) ListModels(ctx context.Context, apiConfig *APIConfig)
if err != nil {
return nil, err
}
- url := fmt.Sprintf("%s?api-version=%s", modelsURL, azureAPIVersion)
+ _, apiVersion := azureCredentials(apiConfig)
+ url := fmt.Sprintf("%s?api-version=%s", modelsURL, url.QueryEscape(apiVersion))
body, err := a.baseModel.doGetRequest(ctx, url, apiConfig, nonStreamCallTimeout)
if err != nil {
diff --git a/internal/entity/models/azure_openai_test.go b/internal/entity/models/azure_openai_test.go
index a2c0ed3b61..497e81a3a2 100644
--- a/internal/entity/models/azure_openai_test.go
+++ b/internal/entity/models/azure_openai_test.go
@@ -353,3 +353,144 @@ func TestAzureEmbedHappyPath(t *testing.T) {
t.Errorf("embedding=%#v", embeddings[0])
}
}
+
+// newAzureCredentialServer answers every Azure data-plane call and records
+// the api-key header and api-version query parameter the request carried.
+func newAzureCredentialServer(gotKey, gotVersion *string) *httptest.Server {
+ return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ *gotKey = r.Header.Get("api-key")
+ *gotVersion = r.URL.Query().Get("api-version")
+ switch {
+ case strings.HasSuffix(r.URL.Path, "/chat/completions") && r.Header.Get("Accept") == "text/event-stream":
+ w.Header().Set("Content-Type", "text/event-stream")
+ _, _ = io.WriteString(w, "data: {\"choices\":[{\"delta\":{\"content\":\"hi\"}}]}\n\ndata: [DONE]\n\n")
+ case strings.HasSuffix(r.URL.Path, "/chat/completions"):
+ _, _ = io.WriteString(w, `{"choices":[{"message":{"role":"assistant","content":"hi"}}]}`)
+ case strings.HasSuffix(r.URL.Path, "/embeddings"):
+ _, _ = io.WriteString(w, `{"data":[{"embedding":[0.1],"index":0}]}`)
+ default:
+ _, _ = io.WriteString(w, `{"data":[{"id":"gpt-4o"}]}`)
+ }
+ }))
+}
+
+// The model settings form stores {"api_key": ..., "api_version": ...} as the
+// instance's api_key whenever an API version is set, which it is by default.
+func TestAzureUnwrapsBundledCredentials(t *testing.T) {
+ withSSRFBypass(t)
+ credentials := []struct {
+ name string
+ apiKey string
+ wantVersion string
+ }{
+ {"plain key", "test-key", azureAPIVersion},
+ {"bundle with api_version", `{"api_key":"test-key","api_version":"2024-02-01"}`, "2024-02-01"},
+ {"bundle with preview api_version", `{"api_key":"test-key","api_version":" 2025-04-01-preview "}`, "2025-04-01-preview"},
+ {"bundle without api_version", `{"api_key":"test-key"}`, azureAPIVersion},
+ {"bundle with blank api_version", `{"api_key":"test-key","api_version":" "}`, azureAPIVersion},
+ }
+ messages := []Message{{Role: "user", Content: "hi"}}
+ deployment := "text-embedding-3-small"
+ calls := []struct {
+ name string
+ call func(m *AzureOpenAIModel, cfg *APIConfig) error
+ }{
+ {"chat", func(m *AzureOpenAIModel, cfg *APIConfig) error {
+ _, err := m.ChatWithMessages(t.Context(), "gpt-4o", messages, cfg, nil, nil)
+ return err
+ }},
+ {"chat stream", func(m *AzureOpenAIModel, cfg *APIConfig) error {
+ return m.ChatStreamlyWithSender(t.Context(), "gpt-4o", messages, cfg, nil, nil,
+ func(*string, *string) error { return nil })
+ }},
+ {"embed", func(m *AzureOpenAIModel, cfg *APIConfig) error {
+ _, err := m.Embed(t.Context(), &deployment, EmbedRequest{Texts: []string{"hi"}}, cfg, nil, nil)
+ return err
+ }},
+ {"list models", func(m *AzureOpenAIModel, cfg *APIConfig) error {
+ _, err := m.ListModels(t.Context(), cfg)
+ return err
+ }},
+ }
+ for _, cred := range credentials {
+ for _, c := range calls {
+ t.Run(cred.name+"/"+c.name, func(t *testing.T) {
+ var gotKey, gotVersion string
+ srv := newAzureCredentialServer(&gotKey, &gotVersion)
+ defer srv.Close()
+
+ apiKey := cred.apiKey
+ if err := c.call(newAzureForTest(srv.URL), &APIConfig{ApiKey: &apiKey}); err != nil {
+ t.Fatalf("unexpected error: %v", err)
+ }
+ if gotKey != "test-key" {
+ t.Errorf("api-key=%q, want test-key", gotKey)
+ }
+ if gotVersion != cred.wantVersion {
+ t.Errorf("api-version=%q, want %s", gotVersion, cred.wantVersion)
+ }
+ })
+ }
+ }
+}
+
+func TestAzureRejectsBundleWithoutAPIKey(t *testing.T) {
+ apiKey := `{"api_key":"","api_version":"2024-02-01"}`
+ _, err := newAzureForTest("http://unused").ChatWithMessages(t.Context(), "gpt-4o",
+ []Message{{Role: "user", Content: "hi"}},
+ &APIConfig{ApiKey: &apiKey}, nil, nil,
+ )
+ if err == nil || !strings.Contains(err.Error(), "api key is required") {
+ t.Fatalf("err=%v, want api key is required", err)
+ }
+}
+
+// stream_options.include_usage is only accepted from API version 2024-09-01
+// on; older versions must still stream, without usage.
+func TestAzureChatStreamSendsUsageOptionWhenSupported(t *testing.T) {
+ withSSRFBypass(t)
+ tests := []struct {
+ apiVersion string
+ wantOption bool
+ }{
+ {"", true},
+ {"2024-02-01", false},
+ {"2024-08-01-preview", false},
+ {"2024-09-01-preview", true},
+ {"2024-10-21", true},
+ {"2025-04-01-preview", true},
+ {"preview", true},
+ }
+ for _, tt := range tests {
+ t.Run(tt.apiVersion, func(t *testing.T) {
+ var gotOption bool
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ var body map[string]interface{}
+ if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+ t.Errorf("decode body: %v", err)
+ }
+ _, gotOption = body["stream_options"]
+ w.Header().Set("Content-Type", "text/event-stream")
+ _, _ = io.WriteString(w, "data: {\"choices\":[{\"delta\":{\"content\":\"hi\"}}]}\n\ndata: [DONE]\n\n")
+ }))
+ defer srv.Close()
+
+ credentials, err := json.Marshal(map[string]string{"api_key": "test-key", "api_version": tt.apiVersion})
+ if err != nil {
+ t.Fatalf("marshal credentials: %v", err)
+ }
+ apiKey := string(credentials)
+ err = newAzureForTest(srv.URL).ChatStreamlyWithSender(t.Context(), "gpt-4o",
+ []Message{{Role: "user", Content: "hi"}},
+ &APIConfig{ApiKey: &apiKey}, nil, nil,
+ func(*string, *string) error { return nil },
+ )
+ if err != nil {
+ t.Fatalf("unexpected error: %v", err)
+ }
+ if gotOption != tt.wantOption {
+ t.Errorf("stream_options sent=%v, want %v", gotOption, tt.wantOption)
+ }
+ })
+ }
+}
diff --git a/web/src/pages/user-setting/setting-model/provider-schema/field-config/provider-config-map.test.ts b/web/src/pages/user-setting/setting-model/provider-schema/field-config/provider-config-map.test.ts
new file mode 100644
index 0000000000..d5b77624ee
--- /dev/null
+++ b/web/src/pages/user-setting/setting-model/provider-schema/field-config/provider-config-map.test.ts
@@ -0,0 +1,53 @@
+import { LLMFactory } from '@/constants/llm';
+import { ProviderConfigMap } from './provider-config-map';
+
+jest.mock('@/components/dynamic-form', () => ({
+ FormFieldType: {
+ Password: 'password',
+ Switch: 'switch',
+ Text: 'text',
+ },
+}));
+
+describe('Azure OpenAI provider configuration', () => {
+ const config = ProviderConfigMap[LLMFactory.AzureOpenAI];
+
+ it('defaults the API version to one that supports streaming usage', () => {
+ expect(
+ config.fields.find((field) => field.name === 'api_version'),
+ ).toMatchObject({ defaultValue: '2024-10-21' });
+ });
+
+ it('verifies with the same credentials it saves', () => {
+ const values = {
+ instance_name: 'azure',
+ api_key: 'test-key',
+ api_version: '2024-02-01',
+ base_url: 'https://example.openai.azure.com/openai',
+ };
+ const credentials = { api_key: 'test-key', api_version: '2024-02-01' };
+
+ expect(config.verifyTransform?.(values)).toMatchObject({
+ apiKey: credentials,
+ });
+ expect(config.submitTransform?.(values)).toMatchObject({
+ api_key: credentials,
+ });
+ });
+
+ it('sends the plain key when no API version is set', () => {
+ const values = {
+ instance_name: 'azure',
+ api_key: 'test-key',
+ api_version: '',
+ base_url: 'https://example.openai.azure.com/openai',
+ };
+
+ expect(config.verifyTransform?.(values)).toMatchObject({
+ apiKey: 'test-key',
+ });
+ expect(config.submitTransform?.(values)).toMatchObject({
+ api_key: 'test-key',
+ });
+ });
+});
diff --git a/web/src/pages/user-setting/setting-model/provider-schema/field-config/provider-config-map.ts b/web/src/pages/user-setting/setting-model/provider-schema/field-config/provider-config-map.ts
index a7810bbb75..06619efb73 100644
--- a/web/src/pages/user-setting/setting-model/provider-schema/field-config/provider-config-map.ts
+++ b/web/src/pages/user-setting/setting-model/provider-schema/field-config/provider-config-map.ts
@@ -19,6 +19,11 @@ import { LLMFactory } from '@/constants/llm';
import type { ProviderConfig } from '../types';
import { parseApiKeyAsObject } from './utils';
+const buildAzureApiKey = (values: Record<string, any>) =>
+ values.api_version
+ ? { api_key: values.api_key ?? '', api_version: values.api_version }
+ : (values.api_key ?? '');
+
const buildMineruApiKey = (values: Record<string, any>) => {
const cfg: Record<string, any> = { ...values };
delete cfg.instance_name;
@@ -76,18 +81,16 @@ export const ProviderConfigMap: Record<string, ProviderConfig> = {
type: FormFieldType.Text,
required: false,
placeholder: 'apiVersionMessage',
- defaultValue: '2024-02-01',
+ defaultValue: '2024-10-21',
},
],
verifyTransform: (values) => ({
- apiKey: values.api_key,
+ apiKey: buildAzureApiKey(values),
baseUrl: values.base_url,
modelInfo: [],
}),
submitTransform: (values) => {
- const apiKey = values.api_version
- ? { api_key: values.api_key ?? '', api_version: values.api_version }
- : (values.api_key ?? '');
+ const apiKey = buildAzureApiKey(values);
return {
instance_name: values.instance_name,
llm_factory: LLMFactory.AzureOpenAI,