Skip to content

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

9.0 KB
Raw Blame
/*
 *  Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */

import { IAddedModel } from '@/interfaces/database/llm';
import { getCachedLlmList } from './llm-cache';

// The names of the large models returned by the interface are similar to "deepseek-r1___OpenAI-API"
export function getRealModelName(llmName: string) {
  return llmName.split('__').at(0) ?? '';
}

// Get tenant model ID from LLM list by model name and factory ID
export function getTenantModelId(
  llmList: Record<string, any>,
  modelName: string,
  factoryId: string,
): string {
  // Iterate through all providers in the LLM list
  for (const [provider, data] of Object.entries(llmList)) {
    if (data.llm && Array.isArray(data.llm)) {
      // Handle /v1/llm/my_llms format
      const model = data.llm.find(
        (m: any) => m.name === modelName && provider === factoryId,
      );
      if (model && model.id) {
        return model.id;
      }
    } else if (Array.isArray(data)) {
      // Handle /v1/llm/list format
      const model = data.find(
        (m: any) => m.llm_name === modelName && m.fid === factoryId,
      );
      if (model && model.id) {
        return model.id;
      }
    }
  }
  return '';
}

/** Build "modelName@instanceName@providerName" */
export function buildModelValue(model: {
  model_name: string;
  model_instance: string;
  model_provider: string;
}) {
  return `${model.model_name}@${model.model_instance}@${model.model_provider}`;
}

/**
 * Identity of a provider model name. The bundled catalog and a live upstream
 * listing can spell the same model with different case or padding, so every
 * merge, lookup and duplicate check compares this normalized form instead of
 * the raw name. Mirrors the backend's `providerModelKey`.
 */
export function modelNameKey(name: string): string {
  return name.trim().toLowerCase();
}

/**
 * Collects every id under which an added model can be referenced — both the
 * model_id form and the legacy "modelName@instanceName@providerName" form —
 * so a persisted form value can be checked against the models that still
 * exist. Mirrors the leaf ids produced by `buildModelTree`.
 */
export function buildValidModelIds(
  allModels: IAddedModel[],
  modelTypes: string[],
): Set<string> {
  const ids = new Set<string>();
  for (const m of allModels) {
    if (
      (m.status != null && m.status !== 'active') ||
      (m.instance_status != null && m.instance_status !== 'active')
    )
      continue;
    if (!m.model_type?.some((t) => modelTypes.includes(t))) continue;
    const legacyId = buildModelValue({
      model_name: getRealModelName(m.name),
      model_instance: m.instance_name,
      model_provider: m.provider_name,
    });
    ids.add(m.model_id || legacyId);
    ids.add(legacyId);
  }
  return ids;
}

/**
 * Parse "modelName@instanceName@providerName" (or the 2-part
 * "modelName@providerName" form where the instance defaults to "default").
 *
 * The composite key is right-anchored: the *last* '@'-separated field is the
 * provider, the second-to-last is the instance, and everything to the left of
 * the second-to-last '@' is the bare model name. Some model names legitimately
 * contain '@' themselves (e.g. LM Studio embedding IDs such as
 * `text-embedding-nomic-embed-text-v1.5@q8_0`), producing four-`@` composite
 * keys like `text-embedding-nomic-embed-text-v1.5@q8_0@lmstudio@LM-Studio`.
 *
 * A naive `split("@")` (or anchoring on the first '@') mis-parses these keys
 * — PATCH /api/v1/models/default then sends `model_name="…v1.5"` and
 * `model_instance="q8_0@lmstudio"`, and the server replies
 * `Instance 'q8_0@lmstudio' not found for provider 'LM-Studio'`.
 *
 * Right-anchored split mirrors `api/db/joint_services/tenant_model_service.py`
 * `split_model_name` and the Go `parseModelName` (PR #16468 family).
 */
export function parseModelValue(val: string) {
  if (!val) return null;
  const lastAt = val.lastIndexOf('@');
  if (lastAt === -1) return null;
  const secondLastAt = val.lastIndexOf('@', lastAt - 1);
  if (secondLastAt === -1) {
    // 2-part form: "modelName@providerName" — instance defaults to "default".
    return {
      model_name: val.substring(0, lastAt),
      model_instance: 'default',
      model_provider: val.substring(lastAt + 1),
    };
  }
  return {
    model_name: val.substring(0, secondLastAt),
    model_instance: val.substring(secondLastAt + 1, lastAt),
    model_provider: val.substring(lastAt + 1),
  };
}

/**
 * Base embedding model name used to decide whether two datasets can be
 * selected and searched together. Composite references
 * ("modelName@instanceName@providerName" or "modelName@providerName") reduce
 * to the bare model name, so datasets using the same embedding model through
 * different provider instances still group together. Opaque values without
 * '@' (e.g. an unresolved tenant_model id) are returned unchanged, so only
 * exact matches group together. Mirrors the backend's base-name comparison
 * (Python `_base_model_name`, Go `common.BaseModelName`).
 */
export function getEmbeddingBaseName(embeddingModel?: string | null): string {
  if (!embeddingModel) return '';
  return parseModelValue(embeddingModel)?.model_name ?? embeddingModel;
}

// Extract model name and factory ID from a model UUID
// Supports both "model_name@factory_id" and "model_name@factory_id#instance_name".
// Uses right-anchored split for the same reason as parseModelValue:
// model names may contain '@' themselves, so a naive split('@') drops the
// last portion of the model name into factoryId.
export function parseModelUuid(uuid: string): {
  modelName: string;
  factoryId: string;
} {
  const hashIndex = uuid.indexOf('#');
  const core = hashIndex === -1 ? uuid : uuid.slice(0, hashIndex);
  const lastAt = core.lastIndexOf('@');
  if (lastAt === -1) {
    return { modelName: core, factoryId: '' };
  }
  return {
    modelName: core.substring(0, lastAt),
    factoryId: core.substring(lastAt + 1),
  };
}

// Model parameter to tenant parameter mapping
type ModelParamMap = {
  [key: string]: string;
};

const modelParamMap: ModelParamMap = {
  llm_id: 'tenant_llm_id',
  embd_id: 'tenant_embd_id',
  asr_id: 'tenant_asr_id',
  tts_id: 'tenant_tts_id',
  img2txt_id: 'tenant_img2txt_id',
  rerank_id: 'tenant_rerank_id',
};

// API endpoint whitelist - only these endpoints will have tenant parameters added
// Note: /api/v1/chats is intentionally absent — the chats API normalizes the
// model name/id pair server-side, so the frontend submits only llm_id /
// rerank_id and must not have a stale tenant_* id injected back in here.
const API_WHITELIST = [
  '/api/v1/users/me/models',
  '/v1/canvas/set',
  '/v1/canvas/setting',
  '/api/v1/searches/',
  '/api/v1/memories',
  '/api/v1/datasets',
  '/v1/dataflow/set',
];

// Check if the URL is in the whitelist
export function isUrlInWhitelist(url: string): boolean {
  return API_WHITELIST.some((endpoint) => url.includes(endpoint));
}

// Add tenant model ID parameters to request data
export function addTenantParams(data: any, url?: string): any {
  if (!data || typeof data !== 'object') return data;

  // Handle arrays
  if (Array.isArray(data)) {
    if (url && !isUrlInWhitelist(url)) return data;
    return data.map((item) => addTenantParams(item, url));
  }

  const newData = { ...data };

  // Clear the paired tenant ID when a model selection is explicitly cleared.
  for (const [paramName, tenantParamName] of Object.entries(modelParamMap)) {
    if (
      Object.hasOwn(newData, paramName) &&
      (newData[paramName] === '' || newData[paramName] == null)
    ) {
      newData[tenantParamName] = null;
    }
  }

  // Non-whitelisted endpoints can clear an explicit model selection, but
  // tenant model IDs are only resolved and injected for whitelisted endpoints.
  if (url && !isUrlInWhitelist(url)) return newData;

  const llmList = getCachedLlmList();
  if (!llmList) return newData;

  for (const [paramName, tenantParamName] of Object.entries(modelParamMap)) {
    if (newData[paramName]) {
      try {
        const { modelName, factoryId } = parseModelUuid(newData[paramName]);
        const tenantModelId = getTenantModelId(llmList, modelName, factoryId);
        if (tenantModelId) {
          newData[tenantParamName] = tenantModelId;
        }
      } catch (error) {
        console.error(`Error processing ${paramName}:`, error);
      }
    }
  }

  // Recursively process nested objects
  for (const [key, value] of Object.entries(newData)) {
    if (value && typeof value === 'object' && !modelParamMap[key]) {
      newData[key] = addTenantParams(value, url);
    }
  }

  return newData;
}