Model Configuration Management

Relevant source files

• README.md
• README_EN.md
• docker-compose.yml
• docs/user/mcp-server.md
• docs/user/mcp-server_en.md
• env.local.example
• mkdocs/docs/zh/user/mcp-server.md
• packages/core/src/index.ts
• packages/core/src/services/image-model/defaults.ts
• packages/core/src/services/image/adapters/modelscope.ts
• packages/core/src/services/llm/adapters/modelscope-adapter.ts
• packages/core/src/services/llm/service.ts
• packages/core/src/services/llm/types.ts
• packages/core/src/services/model/defaults.ts
• packages/core/src/services/model/manager.ts
• packages/core/src/services/model/types.ts
• packages/core/src/services/shared/types.ts
• packages/core/src/utils/environment.ts
• packages/core/tests/unit/image/modelscope-adapter.test.ts
• packages/core/tests/unit/llm/modelscope-adapter.test.ts
• packages/core/tests/unit/model/defaults.test.ts
• packages/core/tests/unit/model/manager.test.ts
• packages/mcp-server/src/config/models.ts
• packages/ui/src/components/ImageModelEditModal.vue
• packages/ui/src/components/ImageModelManager.vue
• packages/ui/src/components/TextModelEditModal.vue
• packages/ui/src/components/TextModelList.vue
• packages/ui/src/components/TextModelManager.vue
• packages/ui/src/components/Toast.vue
• vercel.json

Purpose and Scope

This document details the Model Configuration Management system, which is responsible for managing text model configurations in the Prompt Optimizer application. The ModelManager service handles storage, validation, initialization, and migration of model configurations across all platforms (web, desktop, browser extension).

Key Responsibilities:

• Managing TextModelConfig structures for all text-based LLM providers
• Initializing default configurations from environment variables
• Migrating legacy ModelConfig data to the new TextModelConfig format
• Validating model configurations before storage
• Auto-enabling built-in models when API keys are detected
• Providing CRUD operations for user-defined model configurations

Related Pages:

• For LLM service execution and adapter architecture, see LLM Service and Provider Adapters
• For image model configuration management, see Image Mode Workspaces
• For data persistence mechanisms, see Data Persistence and Storage

Sources: README.md packages/core/src/services/model/manager.ts packages/core/src/services/model/types.ts

Architecture Overview

ModelManager Position in System

The ModelManager sits at the intersection of configuration sources, storage backends, and the adapter registry. It serves as the single source of truth for model configurations, handling both user-defined and built-in models.

Sources: packages/core/src/services/model/manager.ts1-238 packages/ui/src/components/TextModelManager.vue1-153

Configuration Data Structures

TextModelConfig Structure

The TextModelConfig interface represents the modern, self-contained model configuration format introduced in the adapter architecture refactor.

Key Design Principles:

1. Self-Contained Metadata: Each TextModelConfig contains complete copies of providerMeta and modelMeta, eliminating the need for runtime lookups
2. Type Safety: Complete metadata enables compile-time type checking and IDE autocompletion
3. Independence: No inheritance from legacy ModelConfig—this is a clean, new structure
4. Backward Compatibility: The deprecated customParamOverrides field is retained for reading old data but removed on save

Sources: packages/core/src/services/model/types.ts42-80 packages/core/src/services/llm/types.ts8-116

Legacy ModelConfig Structure

The legacy ModelConfig format is maintained for backward compatibility during migration.

Field	Type	Description
name	string	Display name
baseURL	string	API endpoint URL
apiKey	string (optional)	API key
models	string[] (optional)	Available model IDs
defaultModel	string	Selected model ID
enabled	boolean	Enable status
provider	string	Provider identifier (deepseek, gemini, custom, zhipu, etc.)
llmParams	Record<string, any> (optional)	Mixed built-in and custom parameters

Migration Strategy:

The ModelManager automatically detects legacy configurations and converts them to TextModelConfig format during initialization and read operations. The conversion is handled by converter functions that map old field names to new structures.

Sources: packages/core/src/services/model/types.ts84-93 packages/core/src/services/model/converter.ts

Provider and Model Metadata

Provider and model metadata are obtained from the TextAdapterRegistry, which maintains static definitions for all supported providers.

Provider Metadata (TextProvider):

• Sourced from adapter implementations via adapter.getProvider()
• Contains service-level information (API endpoint, requirements, capabilities)
• Includes corsRestricted flag to warn users about browser CORS limitations

Model Metadata (TextModel):

• Sourced from adapter implementations via adapter.getModels()
• Contains model-specific capabilities and parameter schemas
• Defines default parameter values used during initialization

Metadata Patching:

The ModelManager patches stored configurations to backfill missing metadata fields (e.g., corsRestricted) introduced in newer versions:

[manager.ts:244-292] patchProviderMeta()

This ensures configurations created with older versions of the application display correct warnings in the UI.

Sources: packages/core/src/services/llm/types.ts14-76 packages/core/src/services/model/manager.ts244-292

Initialization and Default Generation

Default Model Creation Flow

Initialization Steps:

1. Environment Variable Sync (Electron only): manager.ts80-85

   • Calls ElectronConfigManager.getInstance().syncFromMainProcess()
   • Ensures renderer process has access to main process environment variables

2. Storage Check: manager.ts88-93

   • Loads existing configuration from storage using CORE_SERVICE_KEYS.MODELS

3. Default Model Generation: manager.ts96-110

   • Calls getDefaultModels() to generate configurations for all built-in providers
   • Merges with stored data, adding any missing default models

4. Format Migration: manager.ts144-165

   • Detects legacy ModelConfig structures via isLegacyConfig()
   • Converts using convertLegacyToTextModelConfigWithRegistry() or fallback converter

5. Metadata Patching: manager.ts115-129

   • Patches missing providerMeta or modelMeta fields from registry

6. Auto-Enable Logic: manager.ts132-143

   • Calls shouldAutoEnableBuiltinModel() for each built-in model
   • Enables models if API key is newly detected

Sources: packages/core/src/services/model/manager.ts75-193 packages/core/src/services/model/defaults.ts40-96

Environment Variable Integration

The default model generation system reads API keys and other configuration from environment variables using the getEnvVar() utility.

Provider-to-Environment Variable Mapping:

Generation Process defaults.ts40-96:

1. Iterate through each provider in PROVIDER_ENV_KEYS
2. Get adapter from registry: registry.getAdapter(providerId)
3. Extract provider and model metadata from adapter
4. Read API key from environment: getEnvVar(envKey)
5. Set enabled status based on API key presence: enabled: !!apiKey
6. Initialize paramOverrides with model's defaultParameterValues

Custom Model Configuration:

The custom provider is handled separately defaults.ts71-93:

• Reads VITE_CUSTOM_API_KEY, VITE_CUSTOM_API_BASE_URL, VITE_CUSTOM_API_MODEL
• Uses OpenAI adapter as the provider (custom models follow OpenAI API format)
• Builds a default model with the custom model ID

Dynamic Custom Models:

Multiple custom models can be configured using suffix patterns (e.g., VITE_CUSTOM_API_KEY_ollama). These are generated by generateDynamicModels() model-utils.ts and merged with static models in getAllModels() defaults.ts103-115

Sources: packages/core/src/services/model/defaults.ts1-119 packages/core/src/utils/environment.ts1-300

Auto-Enable Logic

The ModelManager automatically enables built-in models when their API keys are detected during initialization. This feature improves the user experience by reducing manual configuration.

Auto-Enable Conditions manager.ts611-640:

Execution Flow:

1. During initialization, for each stored model, check if it qualifies for auto-enable
2. If conditions are met, merge the new API key and set enabled: true
3. Save updated configuration to storage
4. Log the action: Auto-enabled builtin model with new API key: ${key}

This logic ensures that when users deploy the application with environment variables (e.g., Docker deployment), built-in models are automatically enabled without requiring manual UI configuration.

Sources: packages/core/src/services/model/manager.ts611-640 packages/core/src/services/model/manager.ts132-143

Storage and Persistence

Storage Provider Integration

The ModelManager receives an IStorageProvider instance during construction manager.ts28-36:

The StorageAdapter wraps the provided storage implementation to ensure consistency across different backends (IndexedDB, filesystem, memory).

Storage Operations:

• Read: this.storage.getItem(this.storageKey) manager.ts299-308
• Write: this.storage.setItem(this.storageKey, JSON.stringify(models)) manager.ts171
• Atomic Update: this.storage.updateData<Record<string, any>>(this.storageKey, callback) manager.ts411-426

The updateData() method is particularly important—it provides transactional semantics to prevent race conditions when multiple operations modify the same model configuration.

Sources: packages/core/src/services/model/manager.ts28-36 packages/core/src/services/storage/adapter.ts

Storage Keys

Model configurations are stored under a centralized storage key defined in the constants:

This key is accessed via manager.ts23:

Key Benefits:

• Centralized key management prevents typos and conflicts
• Easy to locate all storage keys used by the application
• Type-safe access through exported constants

Sources: packages/core/src/services/model/manager.ts23 packages/core/src/constants/storage-keys.ts

Data Format

Models are stored as a JSON-serialized object mapping model IDs to TextModelConfig objects:

Storage Format Evolution:

To maintain forward compatibility, the ModelManager removes the deprecated customParamOverrides field when saving manager.ts406-409:

However, it still reads and migrates this field when loading old data manager.ts216-238 ensuring backward compatibility.

Sources: packages/core/src/services/model/manager.ts298-308 packages/core/src/services/model/manager.ts406-409

Configuration Operations

CRUD Operations

The ModelManager implements the IModelManager interface, providing comprehensive CRUD operations for model configurations.

Create (Add Model) manager.ts401-427:

Read (Get Model) manager.ts357-395:

Update (Update Model) manager.ts432-506:

Delete (Delete Model) manager.ts511-526:

List (Get All Models) manager.ts313-352:

Sources: packages/core/src/services/model/manager.ts313-526

Validation

The ModelManager validates TextModelConfig structures before storage using validateTextModelConfig() manager.ts645-697:

Validation Rules:

Check	Error Message
Missing id	"Missing configuration id"
Missing name	"Missing model name (name)"
Invalid providerMeta	"Missing or invalid provider metadata (providerMeta)"
Invalid modelMeta	"Missing or invalid model metadata (modelMeta)"
Missing connectionConfig	"Missing connection configuration (connectionConfig)"
Invalid paramOverrides structure	"paramOverrides must be an object"
Invalid customParamOverrides structure	"customParamOverrides must be an object"

Parameter Validation:

The validator also calls validateOverrides() manager.ts674-685 to check parameter values against the model's parameterDefinitions schema. This ensures:

• Parameter types match schema definitions
• Parameter values are within valid ranges
• Unknown parameters generate warnings (but don't block save)

Validation Errors:

If validation fails, a ModelConfigError is thrown with concatenated error messages manager.ts694-696:

Sources: packages/core/src/services/model/manager.ts645-697 packages/core/src/services/model/parameter-utils.ts

Enable/Disable Operations

The ModelManager provides dedicated methods for toggling model availability without requiring full configuration updates.

Enable Model manager.ts531-567:

Disable Model manager.ts572-604:

Get Enabled Models manager.ts704-708:

Key Behaviors:

• enableModel() performs full validation before enabling (ensures configuration is valid)
• disableModel() does not validate (allows disabling broken configurations)
• Both methods handle legacy format conversion automatically
• Both use atomic updateData() for race condition safety

Sources: packages/core/src/services/model/manager.ts531-708

Migration System

Legacy Format Detection

The migration system uses type guard functions to detect configuration formats.

Type Guards converter.ts:

Detection Flow:

The ModelManager performs this detection during:

• Initialization manager.ts144-165
• getModel() operations manager.ts369-378
• getAllModels() operations manager.ts318-336
• Update operations manager.ts455-461
• Enable/disable operations manager.ts546-594

Sources: packages/core/src/services/model/converter.ts packages/core/src/services/model/manager.ts110-165

Conversion Process

The conversion system provides two conversion paths: registry-based (preferred) and fallback (hardcoded).

Registry-Based Conversion converter.ts:

Fallback Conversion converter.ts:

The fallback converter uses hardcoded default values when the registry is unavailable (e.g., during early initialization or in error scenarios). It constructs minimal but valid TextModelConfig structures.

Parameter Splitting:

The legacy llmParams field mixed built-in parameters (defined in schema) with custom parameters (ad-hoc user additions). The converter splits these using splitOverridesBySchema() parameter-utils.ts:

Sources: packages/core/src/services/model/converter.ts packages/core/src/services/model/parameter-utils.ts

Backward Compatibility

The migration system ensures smooth transitions between versions while maintaining data integrity.

Read-Time Migration manager.ts216-238:

When loading configurations, the ModelManager automatically merges customParamOverrides into paramOverrides:

Write-Time Cleanup manager.ts406-409:

When saving configurations, the deprecated field is removed:

Version Compatibility:

Version	customParamOverrides	paramOverrides	Behavior
Old (< 2.0)	Used	Partial	Only built-in params
Current (2.x)	Deprecated	Primary	All params merged
Future (3.0+)	Removed	Primary	Only paramOverrides exists

Rollback Safety:

The customParamOverrides field is retained (but undefined) during save operations to support potential version rollbacks. If a user downgrades to an older version that expects this field, the data structure remains valid.

Sources: packages/core/src/services/model/manager.ts216-238 packages/core/src/services/model/manager.ts406-409

Provider Metadata Management

Metadata Patching

Over time, new fields may be added to TextProvider and TextModel interfaces. The ModelManager patches stored configurations to backfill missing fields with current adapter definitions.

Provider Metadata Patching manager.ts244-292:

Patching Triggers:

Metadata patching occurs in:

• getAllModels() manager.ts338-351
• getModel() manager.ts383-395

Patching Strategy:

1. Conservative: Only patch fields that are undefined in stored config
2. Non-Destructive: Never overwrite user-customized metadata fields
3. Provider-Aware: Use provider-specific logic (e.g., Ollama correction)
4. Error-Safe: Silently skip patching if registry is unavailable

Sources: packages/core/src/services/model/manager.ts244-292

CORS Restriction Handling

The corsRestricted flag in TextProvider metadata warns users about API endpoints that cannot be accessed directly from browsers due to CORS policies.

CORS-Restricted Providers:

From adapter implementations:

• ModelScope modelscope-adapter.ts38: corsRestricted: true
• Dashscope dashscope-adapter.ts: corsRestricted: true
• Custom APIs: May be restricted depending on server configuration

UI Integration:

The UI displays CORS warnings in multiple places:

1. Model List TextModelList.vue46-52:

2. Connection Test Dialog TextModelManager.vue59-78:

   • Shows warning dialog before testing CORS-restricted APIs in browser
   • Bypassed in Electron environment (no CORS restrictions)

3. Model Edit Modal TextModelEditModal.vue274-291:

   • Same warning dialog before connection testing

Recommendation Flow:

Desktop Application Advantage:

The desktop application (Electron) bypasses all CORS restrictions because it runs core services in the main process with full Node.js capabilities README.md103-105:

✅ 无跨域限制：作为原生桌面应用,它能彻底摆脱浏览器跨域(CORS)问题的困扰

Sources: packages/core/src/services/llm/adapters/modelscope-adapter.ts38 packages/ui/src/components/TextModelList.vue46-52 packages/ui/src/components/TextModelManager.vue59-78

Platform-Specific Adaptations

Electron Environment Integration

The ModelManager integrates with Electron's main process to access environment variables that are not available in the renderer process.

ElectronConfigManager Synchronization manager.ts80-85:

ElectronConfigManager electron-config.ts:

The ElectronConfigManager is a singleton that:

1. Detects Electron renderer environment via isElectronRenderer()
2. Calls window.electronAPI.syncEnvironmentVariables() via IPC
3. Stores synced environment variables in memory
4. Provides generateDefaultModels() method that uses synced values

Configuration Flow:

Why This Is Needed:

In Electron, the renderer process is sandboxed and does not have direct access to Node.js process.env. The contextBridge in the preload script exposes a limited API for secure IPC communication with the main process, where environment variables are accessible.

Sources: packages/core/src/services/model/manager.ts80-85 packages/core/src/services/model/electron-config.ts packages/desktop/electron/preload.js

Browser Environment

In browser environments (web application, browser extension), the ModelManager reads environment variables using Vite's import.meta.env mechanism.

Environment Variable Access environment.ts215-300:

Vite Environment Variable Processing:

Vite processes environment variables at build time:

1. Reads variables from .env.local, .env, etc.
2. Inlines variables prefixed with VITE_ into the bundle
3. Makes them available via import.meta.env in browser code

Security Considerations:

• Only variables prefixed with VITE_ are exposed to browser code
• API keys included in the bundle are visible in browser DevTools
• For production deployments, use environment variables at build time or runtime injection (Docker)

Docker Environment Variable Injection:

In Docker deployments, environment variables are injected at runtime using a script that replaces placeholders in the built JavaScript docker/inject-env.sh:

1. Reads environment variables at container startup
2. Replaces __VITE_*__ placeholders in bundled JS files
3. Allows dynamic configuration without rebuilding the image

Sources: packages/core/src/utils/environment.ts215-300 docker/inject-env.sh vercel.json24-31