🅰️ feat: Azure Config to Allow Different Deployments per Model (#1863)

* wip: first pass for azure endpoint schema

* refactor: azure config to return groupMap and modelConfigMap

* wip: naming and schema changes

* refactor(errorsToString): move to data-provider

* feat: rename to azureGroups, add additional tests, tests all expected outcomes, return errors

* feat(AppService): load Azure groups

* refactor(azure): use imported types, write `mapModelToAzureConfig`

* refactor: move `extractEnvVariable` to data-provider

* refactor(validateAzureGroups): throw on duplicate groups or models; feat(mapModelToAzureConfig): throw if env vars not present, add tests

* refactor(AppService): ensure each model is properly configured on startup

* refactor: deprecate azureOpenAI environment variables in favor of librechat.yaml config

* feat: use helper functions to handle and order enabled/default endpoints; initialize azureOpenAI from config file

* refactor: redefine types as well as load azureOpenAI models from config file

* chore(ci): fix test description naming

* feat(azureOpenAI): use validated model grouping for request authentication

* chore: bump data-provider following rebase

* chore: bump config file version noting significant changes

* feat: add title options and switch azure configs for titling and vision requests

* feat: enable azure plugins from config file

* fix(ci): pass tests

* chore(.env.example): mark `PLUGINS_USE_AZURE` as deprecated

* fix(fetchModels): early return if apiKey not passed

* chore: fix azure config typing

* refactor(mapModelToAzureConfig): return baseURL and headers as well as azureOptions

* feat(createLLM): use `azureOpenAIBasePath`

* feat(parsers): resolveHeaders

* refactor(extractBaseURL): handle invalid input

* feat(OpenAIClient): handle headers and baseURL for azureConfig

* fix(ci): pass `OpenAIClient` tests

* chore: extract env var for azureOpenAI group config, baseURL

* docs: azureOpenAI config setup docs

* feat: safe check of potential conflicting env vars that map to unique placeholders

* fix: reset apiKey when model switches from originally requested model (vision or title)

* chore: linting

* docs: CONFIG_PATH notes in custom_config.md

packages/data-provider/src/azure.ts

@@ -0,0 +1,211 @@
+import type { ZodError } from 'zod';
+import type {
+  TAzureGroups,
+  TAzureGroupMap,
+  TAzureModelGroupMap,
+  TValidatedAzureConfig,
+} from '../src/config';
+import { errorsToString, extractEnvVariable, envVarRegex } from '../src/parsers';
+import { azureGroupConfigsSchema } from '../src/config';
+
+export const deprecatedAzureVariables = [
+  /* "related to" precedes description text */
+  { key: 'AZURE_OPENAI_DEFAULT_MODEL', description: 'setting a default model' },
+  { key: 'AZURE_OPENAI_MODELS', description: 'setting models' },
+  {
+    key: 'AZURE_USE_MODEL_AS_DEPLOYMENT_NAME',
+    description: 'using model names as deployment names',
+  },
+  { key: 'AZURE_API_KEY', description: 'setting a single Azure API key' },
+  { key: 'AZURE_OPENAI_API_INSTANCE_NAME', description: 'setting a single Azure instance name' },
+  {
+    key: 'AZURE_OPENAI_API_DEPLOYMENT_NAME',
+    description: 'setting a single Azure deployment name',
+  },
+  { key: 'AZURE_OPENAI_API_VERSION', description: 'setting a single Azure API version' },
+  {
+    key: 'AZURE_OPENAI_API_COMPLETIONS_DEPLOYMENT_NAME',
+    description: 'setting a single Azure completions deployment name',
+  },
+  {
+    key: 'AZURE_OPENAI_API_EMBEDDINGS_DEPLOYMENT_NAME',
+    description: 'setting a single Azure embeddings deployment name',
+  },
+  {
+    key: 'PLUGINS_USE_AZURE',
+    description: 'using Azure for Plugins',
+  },
+];
+
+export const conflictingAzureVariables = [
+  {
+    key: 'INSTANCE_NAME',
+  },
+  {
+    key: 'DEPLOYMENT_NAME',
+  },
+];
+
+export function validateAzureGroups(configs: TAzureGroups): TValidatedAzureConfig & {
+  isValid: boolean;
+  errors: (ZodError | string)[];
+} {
+  let isValid = true;
+  const modelNames: string[] = [];
+  const modelGroupMap: TAzureModelGroupMap = {};
+  const groupMap: TAzureGroupMap = {};
+  const errors: (ZodError | string)[] = [];
+
+  const result = azureGroupConfigsSchema.safeParse(configs);
+  if (!result.success) {
+    isValid = false;
+    errors.push(errorsToString(result.error.errors));
+  } else {
+    for (const group of result.data) {
+      const {
+        group: groupName,
+        apiKey,
+        instanceName,
+        deploymentName,
+        version,
+        baseURL,
+        additionalHeaders,
+        models,
+      } = group;
+
+      if (groupMap[groupName]) {
+        errors.push(`Duplicate group name detected: "${groupName}". Group names must be unique.`);
+        return { isValid: false, modelNames, modelGroupMap, groupMap, errors };
+      }
+
+      groupMap[groupName] = {
+        apiKey,
+        instanceName,
+        deploymentName,
+        version,
+        baseURL,
+        additionalHeaders,
+        models,
+      };
+
+      for (const modelName in group.models) {
+        modelNames.push(modelName);
+        const model = group.models[modelName];
+
+        if (modelGroupMap[modelName]) {
+          errors.push(
+            `Duplicate model name detected: "${modelName}". Model names must be unique across groups.`,
+          );
+          return { isValid: false, modelNames, modelGroupMap, groupMap, errors };
+        }
+
+        if (typeof model === 'boolean') {
+          // For boolean models, check if group-level deploymentName and version are present.
+          if (!group.deploymentName || !group.version) {
+            errors.push(
+              `Model "${modelName}" in group "${groupName}" is missing a deploymentName or version.`,
+            );
+            return { isValid: false, modelNames, modelGroupMap, groupMap, errors };
+          }
+
+          modelGroupMap[modelName] = {
+            group: groupName,
+          };
+        } else {
+          // For object models, check if deploymentName and version are required but missing.
+          if (
+            (!model.deploymentName && !group.deploymentName) ||
+            (!model.version && !group.version)
+          ) {
+            errors.push(
+              `Model "${modelName}" in group "${groupName}" is missing a required deploymentName or version.`,
+            );
+            return { isValid: false, modelNames, modelGroupMap, groupMap, errors };
+          }
+
+          modelGroupMap[modelName] = {
+            group: groupName,
+            // deploymentName: model.deploymentName || group.deploymentName,
+            // version: model.version || group.version,
+          };
+        }
+      }
+    }
+  }
+
+  return { isValid, modelNames, modelGroupMap, groupMap, errors };
+}
+
+type AzureOptions = {
+  azureOpenAIApiKey: string;
+  azureOpenAIApiInstanceName: string;
+  azureOpenAIApiDeploymentName: string;
+  azureOpenAIApiVersion: string;
+};
+
+type MappedAzureConfig = {
+  azureOptions: AzureOptions;
+  baseURL?: string;
+  headers?: Record<string, string>;
+};
+
+export function mapModelToAzureConfig({
+  modelName,
+  modelGroupMap,
+  groupMap,
+}: Omit<TValidatedAzureConfig, 'modelNames'> & {
+  modelName: string;
+}): MappedAzureConfig {
+  const modelConfig = modelGroupMap[modelName];
+  if (!modelConfig) {
+    throw new Error(`Model named "${modelName}" not found in configuration.`);
+  }
+
+  const groupConfig = groupMap[modelConfig.group];
+  if (!groupConfig) {
+    throw new Error(
+      `Group "${modelConfig.group}" for model "${modelName}" not found in configuration.`,
+    );
+  }
+
+  const modelDetails = groupConfig.models[modelName];
+  const deploymentName =
+    typeof modelDetails === 'object'
+      ? modelDetails.deploymentName || groupConfig.deploymentName
+      : groupConfig.deploymentName;
+  const version =
+    typeof modelDetails === 'object'
+      ? modelDetails.version || groupConfig.version
+      : groupConfig.version;
+
+  if (!deploymentName || !version) {
+    throw new Error(
+      `Model "${modelName}" in group "${modelConfig.group}" is missing a deploymentName ("${deploymentName}") or version ("${version}").`,
+    );
+  }
+
+  const azureOptions: AzureOptions = {
+    azureOpenAIApiKey: extractEnvVariable(groupConfig.apiKey),
+    azureOpenAIApiInstanceName: extractEnvVariable(groupConfig.instanceName),
+    azureOpenAIApiDeploymentName: extractEnvVariable(deploymentName),
+    azureOpenAIApiVersion: extractEnvVariable(version),
+  };
+
+  for (const value of Object.values(azureOptions)) {
+    if (typeof value === 'string' && envVarRegex.test(value)) {
+      throw new Error(`Azure configuration environment variable "${value}" was not found.`);
+    }
+  }
+
+  const result: MappedAzureConfig = { azureOptions };
+
+  if (groupConfig.baseURL) {
+    result.baseURL = extractEnvVariable(groupConfig.baseURL);
+  }
+
+  if (groupConfig.additionalHeaders) {
+    result.headers = groupConfig.additionalHeaders;
+  }
+
+  return result;
+}

packages/data-provider/src/config.ts

@@ -8,6 +8,55 @@ export const defaultSocialLogins = ['google', 'facebook', 'openid', 'github', 'd
 
 export const fileSourceSchema = z.nativeEnum(FileSources);
 
+export const modelConfigSchema = z
+  .object({
+    deploymentName: z.string().optional(),
+    version: z.string().optional(),
+  })
+  .or(z.boolean());
+
+export type TAzureModelConfig = z.infer<typeof modelConfigSchema>;
+
+export const azureBaseSchema = z.object({
+  apiKey: z.string(),
+  instanceName: z.string(),
+  deploymentName: z.string().optional(),
+  version: z.string().optional(),
+  baseURL: z.string().optional(),
+  additionalHeaders: z.record(z.any()).optional(),
+});
+
+export type TAzureBaseSchema = z.infer<typeof azureBaseSchema>;
+
+export const azureGroupSchema = z
+  .object({
+    group: z.string(),
+    models: z.record(z.string(), modelConfigSchema),
+  })
+  .required()
+  .and(azureBaseSchema);
+
+export const azureGroupConfigsSchema = z.array(azureGroupSchema).min(1);
+export type TAzureGroups = z.infer<typeof azureGroupConfigsSchema>;
+
+export type TAzureModelMapSchema = {
+  // deploymentName?: string;
+  // version?: string;
+  group: string;
+};
+
+export type TAzureModelGroupMap = Record<string, TAzureModelMapSchema>;
+export type TAzureGroupMap = Record<
+  string,
+  TAzureBaseSchema & { models: Record<string, TAzureModelConfig> }
+>;
+
+export type TValidatedAzureConfig = {
+  modelNames: string[];
+  modelGroupMap: TAzureModelGroupMap;
+  groupMap: TAzureGroupMap;
+};
+
 export const assistantEndpointSchema = z.object({
   /* assistants specific */
   disableBuilder: z.boolean().optional(),
@@ -56,8 +105,30 @@ export const endpointSchema = z.object({
   headers: z.record(z.any()).optional(),
   addParams: z.record(z.any()).optional(),
   dropParams: z.array(z.string()).optional(),
+  customOrder: z.number().optional(),
 });
 
+export const azureEndpointSchema = z
+  .object({
+    groups: azureGroupConfigsSchema,
+    plugins: z.boolean().optional(),
+  })
+  .and(
+    endpointSchema
+      .pick({
+        titleConvo: true,
+        titleMethod: true,
+        titleModel: true,
+        summarize: true,
+        summaryModel: true,
+        customOrder: true,
+      })
+      .partial(),
+  );
+
+export type TAzureConfig = Omit<z.infer<typeof azureEndpointSchema>, 'groups'> &
+  TValidatedAzureConfig;
+
 export const rateLimitSchema = z.object({
   fileUploads: z
     .object({
@@ -83,6 +154,7 @@ export const configSchema = z.object({
   fileConfig: fileConfigSchema.optional(),
   endpoints: z
     .object({
+      [EModelEndpoint.azureOpenAI]: azureEndpointSchema.optional(),
       [EModelEndpoint.assistants]: assistantEndpointSchema.optional(),
       custom: z.array(endpointSchema.partial()).optional(),
     })
@@ -371,7 +443,7 @@ export enum Constants {
   /**
    * Key for the Custom Config's version (librechat.yaml).
    */
-  CONFIG_VERSION = '1.0.3',
+  CONFIG_VERSION = '1.0.4',
   /**
    * Standard value for the first message's `parentMessageId` value, to indicate no parent exists.
    */

packages/data-provider/src/index.ts

@@ -1,4 +1,5 @@
 /* config */
+export * from './azure';
 export * from './config';
 export * from './file-config';
 /* schema helpers  */

packages/data-provider/src/parsers.ts

@@ -1,5 +1,6 @@
+import type { ZodIssue } from 'zod';
 import type { TConversation, TPreset } from './schemas';
-import type { TEndpointOption } from './types';
+import type { TConfig, TEndpointOption, TEndpointsConfig } from './types';
 import {
   EModelEndpoint,
   openAISchema,
@@ -42,6 +43,101 @@ const endpointSchemas: Record<EModelEndpoint, EndpointSchema> = {
 //   [EModelEndpoint.google]: createGoogleSchema,
 // };
 
+/** Get the enabled endpoints from the `ENDPOINTS` environment variable */
+export function getEnabledEndpoints() {
+  const defaultEndpoints: string[] = [
+    EModelEndpoint.openAI,
+    EModelEndpoint.assistants,
+    EModelEndpoint.azureOpenAI,
+    EModelEndpoint.google,
+    EModelEndpoint.bingAI,
+    EModelEndpoint.chatGPTBrowser,
+    EModelEndpoint.gptPlugins,
+    EModelEndpoint.anthropic,
+  ];
+
+  const endpointsEnv = process.env.ENDPOINTS || '';
+  let enabledEndpoints = defaultEndpoints;
+  if (endpointsEnv) {
+    enabledEndpoints = endpointsEnv
+      .split(',')
+      .filter((endpoint) => endpoint?.trim())
+      .map((endpoint) => endpoint.trim());
+  }
+  return enabledEndpoints;
+}
+
+/** Orders an existing EndpointsConfig object based on enabled endpoint/custom ordering */
+export function orderEndpointsConfig(endpointsConfig: TEndpointsConfig) {
+  if (!endpointsConfig) {
+    return {};
+  }
+  const enabledEndpoints = getEnabledEndpoints();
+  const endpointKeys = Object.keys(endpointsConfig);
+  const defaultCustomIndex = enabledEndpoints.indexOf(EModelEndpoint.custom);
+  return endpointKeys.reduce(
+    (accumulatedConfig: Record<string, TConfig | null | undefined>, currentEndpointKey) => {
+      const isCustom = !(currentEndpointKey in EModelEndpoint);
+      const isEnabled = enabledEndpoints.includes(currentEndpointKey);
+      if (!isEnabled && !isCustom) {
+        return accumulatedConfig;
+      }
+
+      const index = enabledEndpoints.indexOf(currentEndpointKey);
+
+      if (isCustom) {
+        accumulatedConfig[currentEndpointKey] = {
+          order: defaultCustomIndex >= 0 ? defaultCustomIndex : 9999,
+          ...(endpointsConfig[currentEndpointKey] as Omit<TConfig, 'order'> & { order?: number }),
+        };
+      } else if (endpointsConfig[currentEndpointKey]) {
+        accumulatedConfig[currentEndpointKey] = {
+          ...endpointsConfig[currentEndpointKey],
+          order: index,
+        };
+      }
+      return accumulatedConfig;
+    },
+    {},
+  );
+}
+
+/** Converts an array of Zod issues into a string. */
+export function errorsToString(errors: ZodIssue[]) {
+  return errors
+    .map((error) => {
+      const field = error.path.join('.');
+      const message = error.message;
+
+      return `${field}: ${message}`;
+    })
+    .join(' ');
+}
+
+export const envVarRegex = /^\${(.+)}$/;
+
+/** Extracts the value of an environment variable from a string. */
+export function extractEnvVariable(value: string) {
+  const envVarMatch = value.match(envVarRegex);
+  if (envVarMatch) {
+    return process.env[envVarMatch[1]] || value;
+  }
+  return value;
+}
+
+/** Resolves header values to env variables if detected */
+export function resolveHeaders(headers: Record<string, string> | undefined) {
+  const resolvedHeaders = { ...(headers ?? {}) };
+
+  if (headers && typeof headers === 'object' && !Array.isArray(headers)) {
+    Object.keys(headers).forEach((key) => {
+      resolvedHeaders[key] = extractEnvVariable(headers[key]);
+    });
+  }
+
+  return resolvedHeaders;
+}
+
 export function getFirstDefinedValue(possibleValues: string[]) {
   let returnValue;
   for (const value of possibleValues) {