mirror of https://github.com/CherryHQ/cherry-studio.git synced 2026-01-01 09:49:03 +08:00

feat: add utility functions for merging models and providers, including deep merge capabilities

- Implemented mergeObjects function to smartly merge objects, preserving existing values and allowing for configurable overwrite options.
- Added mergeModelsList and mergeProvidersList functions to handle merging of model and provider lists, respectively, with case-insensitive ID matching.
- Introduced preset merge strategies for common use cases.
- Created a new API route for syncing provider models, handling data import and merge operations.
- Developed ModelEditForm and ProviderEditForm components for editing model and provider details, respectively, with form validation and state management.
- Added UI components for labels, selects, and notifications to enhance user experience.

2025-12-24 01:29:07 +08:00

4.4 KiB

Raw Blame History

Cherry Studio Catalog

Comprehensive AI model catalog with provider information, pricing, capabilities, and automatic synchronization.

Quick Start

1. Setup API Keys

Most providers require API keys to list models:

# Copy example file
cp .env.example .env

# Edit .env and add your API keys
# OPENAI_API_KEY=sk-...
# GROQ_API_KEY=gsk_...
# DEEPSEEK_API_KEY=...

2. Sync Provider Models

Option A: Sync all providers (batch)

npm run sync:all

Option B: Import authoritative sources

# OpenRouter (360+ models)
npm run import:openrouter

# AIHubMix (600+ models)
npm run import:aihubmix

Option C: Use Web UI

cd web
npm run dev
# Open http://localhost:3000/providers
# Click "Sync" button on any provider

Features

Provider Management

✅ 51 providers configured with API endpoints
✅ Automatic model discovery via models_api
✅ Support for multiple API formats (OpenAI, Anthropic, Gemini)
✅ Custom transformers for aggregators

Model Catalog

✅ 1000+ models from various providers
✅ Comprehensive metadata (pricing, capabilities, limits)
✅ Input/output modalities
✅ Case-insensitive model IDs

Override System

✅ Provider-specific model overrides
✅ Tracks all provider-supported models (even if identical)
✅ Smart merging (preserves manual edits)
✅ Priority system (auto < 100 < manual)
✅ Automatic deduplication

Synchronization

✅ Batch sync all providers
✅ Per-provider sync via Web UI
✅ API key management
✅ Rate limiting and error handling

Data Files

data/
├── models.json       # Base model catalog (authoritative)
├── providers.json    # Provider configurations with models_api
└── overrides.json    # Provider-specific model overrides

Scripts

Command	Description
`npm run sync:all`	Sync all providers (except OpenRouter/AIHubMix)
`npm run import:openrouter`	Import models from OpenRouter
`npm run import:aihubmix`	Import models from AIHubMix
`npm run build`	Build TypeScript package
`npm run test`	Run test suite

Architecture

Transformers

Transform provider API responses to internal format:

OpenAI-compatible (default): Standard /v1/models format
OpenRouter: Custom aggregator format with advanced capabilities
AIHubMix: CSV-based format with type/feature parsing

Data Flow

Provider API → Transformer → ModelConfig[]
                                 ↓
                    Compare with models.json
                                 ↓
              ┌──────────────────┴─────────────────┐
              ↓                                     ↓
        New Model                            Existing Model
              ↓                                     ↓
    Add to models.json                    Generate Override
                                                    ↓
                                          Merge with existing
                                                    ↓
                                            Save to overrides.json

Documentation

Sync Guide - Detailed synchronization documentation
Schema Documentation - Data schemas and validation

Development

Prerequisites

Node.js 18+
Yarn 4+

Setup

# Install dependencies
yarn install

# Run tests
npm run test

# Build package
npm run build

# Watch mode
npm run dev

Adding a Provider

Add provider config to data/providers.json:

{
  "id": "new-provider",
  "name": "New Provider",
  "models_api": {
    "endpoints": [
      {
        "url": "https://api.provider.com/v1/models",
        "endpoint_type": "CHAT_COMPLETIONS",
        "format": "OPENAI"
      }
    ],
    "enabled": true,
    "update_frequency": "daily"
  }
}

Add API key mapping in scripts/sync-all-providers.ts:

const PROVIDER_ENV_MAP: Record<string, string> = {
  // ...
  'new-provider': 'NEW_PROVIDER_API_KEY'
}

Add to .env.example:

NEW_PROVIDER_API_KEY=

Run sync:

npm run sync:all

Adding a Custom Transformer

See Transformers Guide for details.

License

MIT

Contributing

Contributions welcome! Please read the Sync Guide first.

4.4 KiB Raw Blame History