自定义模型接入

自定义模型接入支持本地部署模型和第三方 API,提供数据安全和成本优化的解决方案。

适用场景

数据安全需求

企业内网部署: 数据不出网,满足合规要求
敏感数据处理: 金融、医疗等行业的隐私保护
定制化训练: 基于企业数据微调的专属模型

成本优化需求

高频调用: 本地部署免除 API 调用费用
长期使用: 一次性硬件投入,长期收益
资源复用: 多业务共享模型资源

技术需求

特殊模型: 使用不在主流平台的模型
定制功能: 需要特殊的 API 功能
混合部署: 云端 + 本地混合架构

提供商类型

Local (本地部署)

适用场景: 使用本地部署的开源模型

支持的部署方式:

Ollama - 最简单的本地模型部署方案
vLLM - 高性能推理服务器
LocalAI - OpenAI 兼容的本地推理
Text Generation WebUI - Gradio 界面的本地模型
FastChat - 多模型对话服务

HuggingFace TEI

适用场景: 接入自部署的 Text Embeddings Inference (TEI) 服务，用于 embedding / rerank

说明:

提供商代码 tei，API Base URL 默认 http://reranker:80
容器已绑定具体模型，模型名仅用于展示
本地 rerank（进程内推理）已于 2026-06-12 移除；rerank 现仅支持远程 API —— 自部署的 TEI 服务是推荐方案

Custom (自定义 API)

适用场景: 接入任意兼容 OpenAI 格式的 API

支持的 API:

自建模型 API 服务
第三方 LLM 平台
中转/代理 API
定制化模型服务

Ollama 部署 (推荐)

安装 Ollama

macOS / Linux:

bash

curl -fsSL https://ollama.com/install.sh | sh

Windows: 访问 https://ollama.com/download 下载安装包

Docker 部署:

bash

docker run -d \
  -v ollama:/root/.ollama \
  -p 11434:11434 \
  --name ollama \
  ollama/ollama

下载模型

bash

# 下载 Llama 3.1
ollama pull llama3.1

# 下载 Qwen 2.5
ollama pull qwen2.5:7b

# 下载 DeepSeek Coder
ollama pull deepseek-coder

# 下载嵌入模型
ollama pull nomic-embed-text

# 查看已安装模型
ollama list

启动服务

bash

# 启动 Ollama 服务 (默认端口 11434)
ollama serve

# 测试 API
curl http://localhost:11434/v1/models

在 Sira AI 中配置

添加模型:
- 进入 AI 模型配置 → 模型管理 → 添加模型
- 名称: Llama 3.1 本地
- 提供商: local
- 模型标识: llama3.1 (Ollama 中的模型名)
- 模型类型: 勾选 LLM
配置 API:
- API Base URL: http://localhost:11434/v1
- API Key: 留空(Ollama 不需要)
调整参数:
- Temperature: 0.7
- Max Tokens: 2000
保存并测试

Ollama API 格式

Ollama 提供 OpenAI 兼容的 API (/v1/chat/completions),无需额外配置。

vLLM 部署 (高性能)

安装 vLLM

bash

# 创建虚拟环境
conda create -n vllm python=3.10
conda activate vllm

# 安装 vLLM
pip install vllm

# GPU 驱动要求: CUDA 11.8+

启动模型服务

bash

# 启动 Llama 3.1-8B
python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Meta-Llama-3.1-8B-Instruct \
  --port 8000 \
  --tensor-parallel-size 1

# 多 GPU 并行
python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Meta-Llama-3.1-70B-Instruct \
  --port 8000 \
  --tensor-parallel-size 4  # 使用 4 张 GPU

在 Sira AI 中配置

添加模型:
- 名称: Llama 3.1-8B vLLM
- 提供商: local
- 模型标识: meta-llama/Meta-Llama-3.1-8B-Instruct
- 模型类型: 勾选 LLM
配置 API:
- API Base URL: http://localhost:8000/v1
- API Key: 留空

性能优化:

Temperature: 0.7
Max Tokens: 4000

自定义请求参数 (extraBody):

json

{
  "max_tokens": 4000,
  "top_p": 0.9,
  "frequency_penalty": 0.0
}

LocalAI 部署

Docker 部署

bash

# 创建 docker-compose.yml
cat > docker-compose.yml << 'YAML'
version: '3.6'
services:
  localai:
    image: localai/localai:latest
    ports:
      - "8080:8080"
    volumes:
      - ./models:/models
    environment:
      - THREADS=4
      - CONTEXT_SIZE=4096
YAML

# 启动服务
docker-compose up -d

# 下载模型
docker exec localai \
  wget https://huggingface.co/TheBloke/Llama-2-7B-Chat-GGUF/resolve/main/llama-2-7b-chat.Q4_K_M.gguf \
  -O /models/llama-2-7b-chat.Q4_K_M.gguf

在 Sira AI 中配置

添加模型:
- 名称: Llama 2 LocalAI
- 提供商: local
- 模型标识: llama-2-7b-chat.Q4_K_M.gguf
- 模型类型: 勾选 LLM
配置 API:
- API Base URL: http://localhost:8080/v1
- API Key: 留空

自定义 API 接入

兼容 OpenAI 格式的 API

示例: 自建模型 API

bash

# 你的自建 API 端点
POST https://your-api.example.com/v1/chat/completions

# 请求格式 (与 OpenAI 相同)
{
  "model": "your-model-name",
  "messages": [
    {"role": "user", "content": "Hello"}
  ],
  "temperature": 0.7
}

在 Sira AI 中配置:

添加模型:
- 名称: 自建模型
- 提供商: custom
- 模型标识: your-model-name
- 模型类型: 根据功能勾选
配置 API:
- API Base URL: https://your-api.example.com/v1
- API Key: 如有需要填写
额外请求参数 (extra_body): 在「高级配置」折叠区填写 JSON，直接透传给模型 API：
json
```
{
  "custom_param1": "value1",
  "custom_param2": "value2"
}
```

旧版的「自定义请求头 (customHeaders)」「提供商特定参数 (providerSpecificParams)」字段已不存在 —— 所有自定义参数统一走 extra_body（Claude 不支持）。

第三方平台接入

示例 1: Together AI

提供商: custom
API Base URL: https://api.together.xyz/v1
API Key: 你的Together API Key
模型标识: meta-llama/Llama-3.1-70B-Instruct-Turbo

示例 2: Replicate API

需要自定义适配层,将 Replicate 格式转换为 OpenAI 格式。

示例 3: Hugging Face Inference API

提供商: custom
API Base URL: https://api-inference.huggingface.co/models
API Key: 你的HF Token
模型标识: meta-llama/Meta-Llama-3-8B-Instruct

嵌入模型部署

Ollama 嵌入模型

bash

# 下载嵌入模型
ollama pull nomic-embed-text

# 测试
curl http://localhost:11434/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nomic-embed-text",
    "input": "Hello world"
  }'

在 Sira AI 中配置:

提供商: local
模型标识: nomic-embed-text
模型类型: 仅勾选 EMBEDDING
API Base URL: http://localhost:11434/v1

自建嵌入服务

使用 FastAPI 部署 BGE-M3:

python

from fastapi import FastAPI
from sentence_transformers import SentenceTransformer

app = FastAPI()
model = SentenceTransformer('BAAI/bge-m3')

@app.post("/v1/embeddings")
async def get_embeddings(request: dict):
    text = request['input']
    embeddings = model.encode(text).tolist()
    return {
        "object": "list",
        "data": [
            {
                "object": "embedding",
                "embedding": embeddings,
                "index": 0
            }
        ],
        "model": "bge-m3"
    }

# 运行: uvicorn main:app --host 0.0.0.0 --port 8000

在 Sira AI 中配置:

提供商: custom
模型标识: bge-m3
模型类型: 仅勾选 EMBEDDING
API Base URL: http://localhost:8000

重排序模型部署

rerank 仅支持远程 API

内置的本地 rerank（进程内推理）已于 2026-06-12 移除。rerank 现在只能走远程 API。推荐用 tei 提供商接入自部署的 TEI 服务（默认 http://reranker:80）；下面的"自建 FastAPI 重排序服务 + custom 提供商"是另一种远程 API 方案。

自建重排序服务

使用 FastAPI 部署 BGE-Reranker:

python

from fastapi import FastAPI
from sentence_transformers import CrossEncoder

app = FastAPI()
model = CrossEncoder('BAAI/bge-reranker-v2-m3')

@app.post("/v1/rerank")
async def rerank(request: dict):
    query = request['query']
    documents = request['documents']
    
    # 计算相关性分数
    scores = model.predict([(query, doc) for doc in documents])
    
    # 排序
    ranked = sorted(
        enumerate(scores), 
        key=lambda x: x[1], 
        reverse=True
    )
    
    return {
        "results": [
            {
                "index": idx,
                "relevance_score": float(score),
                "document": documents[idx]
            }
            for idx, score in ranked
        ]
    }

# 运行: uvicorn main:app --host 0.0.0.0 --port 8001

在 Sira AI 中配置:

提供商: custom
模型标识: bge-reranker-v2-m3
模型类型: 仅勾选 RERANK
API Base URL: http://localhost:8001

硬件要求

LLM 推理

模型大小	最低显存	推荐显存	推荐 GPU
7B	8GB	12GB	RTX 3060, RTX 4060 Ti
13B	16GB	24GB	RTX 3090, RTX 4090
34B	24GB	48GB	A100 40GB x2
70B	48GB	80GB	A100 80GB, H100

Embedding/Rerank 模型

模型	最低内存	推荐配置
BGE-M3	4GB RAM	8GB RAM
BGE-Large	2GB RAM	4GB RAM
BGE-Reranker	4GB RAM	8GB RAM

量化技术

使用 4-bit 或 8-bit 量化可以大幅降低显存需求,7B 模型只需 4GB 显存。

性能优化

推理加速

1. 批处理 (Batch Processing):

json

{
  "max_batch_size": 32,
  "max_waiting_time_ms": 100
}

2. 量化 (Quantization):

INT8: 减少50%显存,性能损失 < 1%
INT4: 减少75%显存,性能损失 2-3%

3. 并行推理:

多 GPU 并行 (Tensor Parallelism)
多实例负载均衡

4. KV Cache 优化:

json

{
  "gpu_memory_utilization": 0.9,
  "max_num_seqs": 256
}

延迟优化

减少网络延迟:

本地部署在同一网络环境
使用 HTTP/2 或 gRPC

启用流式响应:

json

{
  "stream": true
}

监控和日志

Ollama 日志

bash

# 查看日志
journalctl -u ollama -f

# 检查模型状态
ollama ps

# 查看模型详情
ollama show llama3.1

vLLM 监控

python

# 启动时启用 Prometheus metrics
python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Meta-Llama-3.1-8B-Instruct \
  --port 8000 \
  --enable-metrics

# 访问 metrics: http://localhost:8000/metrics

自定义 API 日志

在 Sira AI 中查看请求日志:

系统设置 → 日志管理
筛选模型 ID
查看请求/响应详情
分析错误和性能

故障排查

Ollama 相关

问题: 模型下载失败

bash

# 检查磁盘空间
df -h

# 手动下载模型
ollama pull llama3.1 --verbose

# 检查网络连接
curl -I https://ollama.com

问题: 服务无法启动

bash

# 检查端口占用
lsof -i :11434

# 重启服务
systemctl restart ollama

# 查看详细日志
journalctl -u ollama -n 100

vLLM 相关

问题: OOM (显存不足)

python

# 减少最大序列长度
--max-model-len 2048

# 降低 batch size
--max-num-seqs 128

# 使用量化
--quantization awq

问题: 推理速度慢

python

# 增加 GPU 利用率
--gpu-memory-utilization 0.95

# 启用更多并行
--tensor-parallel-size 2

自定义 API 相关

问题: 连接超时

检查 API Base URL 是否正确
确认服务器可访问
增加 Timeout 设置

问题: 认证失败

检查 API Key 是否正确
如上游需要额外鉴权参数，确认 extra_body 配置
查看 API 文档的认证方式

问题: 响应格式错误

确保 API 兼容 OpenAI 格式
检查返回的 JSON 结构
查看 Sira AI 日志中的详细错误

安全建议

网络安全

本地部署: 不要暴露到公网
内网访问: 使用 VPN 或专线
防火墙: 仅允许必要端口

访问控制

API Key: 即使本地也要设置认证
IP 白名单: 限制访问来源
HTTPS: 使用 TLS 加密传输

数据安全

日志脱敏: 不要记录敏感信息
定期备份: 备份模型和配置
权限管理: 最小权限原则

成本分析

硬件投入

7B 模型推理服务器:

RTX 4090 24GB: ¥15,000
服务器主机: ¥10,000
总计: ¥25,000

70B 模型推理服务器:

A100 80GB x2: ¥200,000
服务器主机: ¥50,000
总计: ¥250,000

ROI 分析

场景: 日均 10万次调用

云端 API 成本:

GPT-4o: $5-15 / 1M tokens
月成本: $15,000 - $45,000

本地部署成本:

硬件折旧: $500/月 (5年折旧)
电费: $200/月
维护: $300/月
月成本: $1,000

ROI: 1-2 个月回本

常见问题

部署相关

Q: Ollama 和 vLLM 如何选择?

Ollama: 简单易用,适合快速体验和小规模部署
vLLM: 高性能,适合生产环境和大规模部署

Q: 需要什么样的 GPU?

7B 模型: RTX 3060/4060 Ti 即可
13B 模型: RTX 3090/4090
70B 模型: A100 或多卡并行

Q: 可以使用 CPU 推理吗?

A: 可以,但速度会很慢。7B 模型 CPU 推理约 5-10 tokens/s,GPU 可达 50-100 tokens/s。

性能相关

Q: 本地模型和云端 API 质量差异大吗?

Llama 3.1-70B 接近 GPT-4 水平
Llama 3.1-8B 接近 GPT-3.5 水平
具体效果取决于任务类型

Q: 如何提升推理速度?

使用量化 (INT8/INT4)
启用并行推理
优化 batch size
使用 vLLM 等高性能引擎

Q: 支持多语言吗?

A: 是的,Llama 3.1、Qwen 等模型都支持中英文。中文任务推荐使用 Qwen 或 DeepSeek。

下一步

模型管理 - 配置和测试自定义模型
多模型配置 - 组合使用多种模型
创建 Agent - 在 Agent 中使用自定义模型
模型策略 - 多模型选择策略

自定义模型接入 ​

适用场景 ​

数据安全需求 ​

成本优化需求 ​

技术需求 ​

提供商类型 ​

Local (本地部署) ​

HuggingFace TEI ​

Custom (自定义 API) ​

Ollama 部署 (推荐) ​

安装 Ollama ​

下载模型 ​

启动服务 ​

在 Sira AI 中配置 ​

vLLM 部署 (高性能) ​

安装 vLLM ​

启动模型服务 ​

在 Sira AI 中配置 ​

LocalAI 部署 ​

Docker 部署 ​

在 Sira AI 中配置 ​

自定义 API 接入 ​

兼容 OpenAI 格式的 API ​

第三方平台接入 ​

嵌入模型部署 ​

Ollama 嵌入模型 ​

自建嵌入服务 ​

重排序模型部署 ​

自建重排序服务 ​

硬件要求 ​

LLM 推理 ​

Embedding/Rerank 模型 ​

性能优化 ​

推理加速 ​

延迟优化 ​

监控和日志 ​

Ollama 日志 ​

vLLM 监控 ​

自定义 API 日志 ​

故障排查 ​

Ollama 相关 ​

vLLM 相关 ​

自定义 API 相关 ​

安全建议 ​

网络安全 ​

访问控制 ​

数据安全 ​

成本分析 ​

硬件投入 ​

ROI 分析 ​

常见问题 ​

部署相关 ​

性能相关 ​

下一步 ​

自定义模型接入

适用场景

数据安全需求

成本优化需求

技术需求

提供商类型

Local (本地部署)

HuggingFace TEI

Custom (自定义 API)

Ollama 部署 (推荐)

安装 Ollama

下载模型

启动服务

在 Sira AI 中配置

vLLM 部署 (高性能)

安装 vLLM

启动模型服务

在 Sira AI 中配置

LocalAI 部署

Docker 部署

在 Sira AI 中配置

自定义 API 接入

兼容 OpenAI 格式的 API

第三方平台接入

嵌入模型部署

Ollama 嵌入模型

自建嵌入服务

重排序模型部署

自建重排序服务

硬件要求

LLM 推理

Embedding/Rerank 模型

性能优化

推理加速

延迟优化

监控和日志

Ollama 日志

vLLM 监控

自定义 API 日志

故障排查

Ollama 相关

vLLM 相关

自定义 API 相关

安全建议

网络安全

访问控制

数据安全

成本分析

硬件投入

ROI 分析

常见问题

部署相关

性能相关

下一步