xinmi/docs/wiki/核心功能/内置模型管理.md

---
title: 内置模型管理
tags: [核心功能, 模型, 系统管理, 内置服务]
aliases: [内置模型, BuiltinModel, BUILTIN_MODELS]
source: BUILTIN_MODELS.md
---

# 内置模型管理指南

## 概述

内置模型是系统级别的模型配置，对所有空间可见，但敏感信息会被隐藏，且不可编辑或删除。内置模型通常用于提供系统默认的模型配置，确保所有空间都能使用统一的模型服务。

> 同为内置系统配置的还有 [内置MCP服务管理](内置MCP服务管理.md)

## 内置模型特性

- **所有空间可见**：无需单独配置
- **安全保护**：API Key、Base URL 被隐藏
- **只读保护**：不能被编辑或删除，只能设置为默认模型
- **统一管理**：由系统管理员统一维护

## 如何添加内置模型

### 1. 准备模型数据

- 模型名称（name）
- 模型类型（type）：`KnowledgeQA`、`Embedding`、`Rerank` 或 `VLLM`
- 模型来源（source）：`local` 或 `remote`
- 模型参数（parameters）：包括 base_url、api_key、provider 等
- 空间ID（tenant_id）：建议使用小于10000的空间ID

**支持的服务商（provider）**：`generic`、`openai`、`aliyun`、`zhipu`、`volcengine`、`hunyuan`、`deepseek`、`minimax`、`mimo`、`siliconflow`、`jina`、`openrouter`、`litellm`、`requesty`、`gemini`、`modelscope`、`moonshot`、`qianfan`、`qiniu`、`longcat`、`gpustack`

### 2. 执行 SQL 插入语句

```sql
-- LLM 内置模型
INSERT INTO models (
    id, tenant_id, name, type, source, description, parameters,
    is_default, status, is_builtin
) VALUES (
    'builtin-llm-001', 10000, 'GPT-4', 'KnowledgeQA', 'remote',
    '内置 LLM 模型',
    '{"base_url": "https://api.openai.com/v1", "api_key": "sk-xxx", "provider": "openai"}'::jsonb,
    false, 'active', true
) ON CONFLICT (id) DO NOTHING;

-- Embedding 内置模型
INSERT INTO models (...) VALUES (...) ON CONFLICT (id) DO NOTHING;

-- Rerank 内置模型
INSERT INTO models (...) VALUES (...) ON CONFLICT (id) DO NOTHING;
```

### 3. 验证

```sql
SELECT id, name, type, is_builtin, status
FROM models WHERE is_builtin = true ORDER BY type, created_at;
```

## 注意事项

1. **ID 命名规范**：建议使用 `builtin-{type}-{序号}` 格式
2. **空间ID**：建议使用第一个空间ID（通常是 10000）
3. **参数格式**：`parameters` 字段必须是有效的 JSON 格式
4. **幂等性**：使用 `ON CONFLICT (id) DO NOTHING`
5. **安全性**：API Key 和 Base URL 在前端会被自动隐藏

## 模型配置与常见问题

- 如果 Embedding 模型未正确配置，会导致文档无法上传。排查步骤参见 [常见问题](../运维排障/常见问题.md)
- 模型参数中的 `provider` 决定了 API 调用格式和认证方式

---

## 反向链接

- [Home](../Home.md) — Wiki 首页导航
- [内置MCP服务管理](../核心功能/内置MCP服务管理.md) — 同为内置系统配置，模式相似
- [常见问题](../运维排障/常见问题.md) — 模型配置相关的故障排查
- [版本路线图](../项目概述/版本路线图.md) — 路线图中模型训练方向