> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-zh/ai-ping-tai-yu-zhi-neng-ti/jan.md).

# Jan.ai 离线助手

在 Clore.ai 上部署 Jan.ai Server——一个完全离线、兼容 OpenAI 的 LLM 服务器，具有模型中心、对话管理和由 Cortex 引擎驱动的 GPU 加速推理。

## 概览

[Jan.ai](https://github.com/janhq/jan) 是一个开源、隐私优先的 ChatGPT 替代方案，GitHub 星标超过 40,000。Jan 最出名的是桌面应用，但其服务器组件—— **Jan Server** ——提供了一个完全兼容 OpenAI 的 REST API，可部署在 Clore.ai 之类的云 GPU 基础设施上。

Jan Server 基于 [Cortex.cpp](https://github.com/janhq/cortex.cpp) 推理引擎构建，这是一个支持 `llama.cpp`, `TensorRT-LLM`和 ONNX 后端的高性能运行时。在 Clore.ai 上，你最低只需 **$0.20/小时**，就能通过 Docker Compose 运行 Jan Server，加载任意 GGUF 或 GPTQ 模型，并通过兼容 OpenAI 的 API 提供服务——所有数据都不会离开机器。

**主要特性：**

* 🔒 100% 离线——没有任何数据会离开你的服务器
* 🤖 兼容 OpenAI 的 API（`/v1/chat/completions`, `/v1/models`等）
* 📦 模型中心，支持一键下载模型
* 🚀 通过 CUDA 加速（llama.cpp + TensorRT-LLM 后端）
* 💬 内置对话管理和线程历史记录
* 🔌 可直接替换现有应用中的 OpenAI

***

## 需求

{% hint style="warning" %}
**Clore.ai 市场上未列出多 GPU 的 80GB 级机型。** 目前列出的最大配置是 4× RTX PRO 6000 Blackwell（每张 96GB，共 380GB）以及 8–11× RTX 5090（每张 32GB）。A100 / H200 / B200 容量可按 [裸机](https://clore.ai/bare-metal) 需求提供。部署前请查看 [GPU 价格与可用性](/guides/guides_v2-zh/ru-men-zhi-nan/pricing.md) 。
{% endhint %}

### 硬件要求

| 层级       | GPU           | 显存    | 内存     | 存储         | Clore.ai 价格                       |
| -------- | ------------- | ----- | ------ | ---------- | --------------------------------- |
| **最低**   | RTX 3060 12GB | 12 GB | 16 GB  | 50 GB SSD  | $0.03–0.07/小时                     |
| **推荐**   | RTX 3090      | 24 GB | 32 GB  | 100 GB SSD | $0.07–0.21/小时                     |
| **高端**   | RTX 4090      | 24 GB | 64 GB  | 200 GB SSD | $0.14–0.42/小时                     |
| **大型模型** | A100 80GB     | 80 GB | 128 GB | 500 GB SSD | [裸机](https://clore.ai/bare-metal) |

### 模型 VRAM 参考

| 模型                 | 所需显存     | 推荐 GPU       |
| ------------------ | -------- | ------------ |
| Llama 3.1 8B（Q4）   | \~5 GB   | RTX 3060     |
| Llama 3.1 8B（FP16） | 约 16 GB  | RTX 3090     |
| Llama 3.3 70B（Q4）  | 约 40 GB  | A100 40GB    |
| Llama 3.1 405B（Q4） | 约 220 GB | 4× A100 80GB |
| Mistral 7B（Q4）     | 约 4 GB   | RTX 3060     |
| Qwen2.5 72B（Q4）    | 约 45 GB  | A100 80GB    |

### 软件前置条件

* 已充值钱包的 Clore.ai 账户
* 基础 Docker 知识
* （可选）用于端口转发的 OpenSSH 客户端

***

## 快速开始

### 第 1 步——在 Clore.ai 上租用 GPU 服务器

1. 浏览到 [clore.ai](https://clore.ai) 并登录
2. 筛选服务器： **GPU 类型** → RTX 3090 或更高， **Docker** → 已启用
3. 选择一台服务器并选择 **Docker** 部署选项
4. 使用官方 `nvidia/cuda:12.8.1-devel-ubuntu22.04` 基础镜像或任意 CUDA 镜像
5. 开放端口： **1337** （Jan Server API）， **39281** （Cortex API）， **22** （SSH）

### 第 2 步——连接到你的服务器

```bash
# 通过 SSH 登录你的 Clore.ai 服务器
ssh -p <CLORE_SSH_PORT> root@<CLORE_SERVER_IP>

# 验证 GPU 是否可用
nvidia-smi
```

### 第 3 步——安装 Docker Compose（如果尚未安装）

```bash
# 检查 Docker Compose 是否可用
docker compose version

# 如果缺失则安装（Ubuntu/Debian）
apt-get update && apt-get install -y docker-compose-plugin

# 验证
docker compose version
```

### 第 4 步——使用 Docker Compose 部署 Jan Server

```bash
# 创建工作目录
mkdir -p /workspace/jan-server && cd /workspace/jan-server

# 下载官方 Jan Server docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/janhq/jan-server/main/docker-compose.yml \
  -o docker-compose.yml

# 查看并编辑配置
cat docker-compose.yml
```

如果上游 compose 文件不可用，或者你想要完全控制，可以手动创建：

```yaml
# /workspace/jan-server/docker-compose.yml
version: '3.8'

services:
  jan-server:
    image: ghcr.io/janhq/cortex:latest
    container_name: jan-server
    restart: unless-stopped
    ports:
      - "1337:1337"
      - "39281:39281"
    volumes:
      - jan-data:/root/jan
      - jan-models:/root/cortex/models
    environment:
      - CUDA_VISIBLE_DEVICES=0
      - JAN_API_HOST=0.0.0.0
      - JAN_API_PORT=1337
      - CORTEX_API_PORT=39281
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:1337/health"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 60s

volumes:
  jan-data:
    driver: local
  jan-models:
    driver: local
```

```bash
# 启动 Jan Server
docker compose up -d

# 查看启动日志（等待出现“Server started”消息）
docker compose logs -f jan-server
```

### 第 5 步——验证服务器是否正在运行

```bash
# 检查服务器健康状态
curl http://localhost:1337/health

# 列出可用模型（初始为空）
curl http://localhost:1337/v1/models

# 预期响应：
# {"object":"list","data":[]}
```

### 第 6 步——拉取你的第一个模型

```bash
# 拉取 Llama 3.2 3B（适合入门，约 2GB）
curl -X POST http://localhost:1337/v1/models/pull \
  -H "Content-Type: application/json" \\
  -d '{"model": "llama3.2:3b-gguf-q4-km"}'

# 或拉取 Mistral 7B Instruct Q4
curl -X POST http://localhost:1337/v1/models/pull \
  -H "Content-Type: application/json" \\
  -d '{"model": "mistral:7b-instruct-v0.3-gguf-q4-km"}'

# 监控下载进度
curl http://localhost:1337/v1/models
```

### 第 7 步——启动模型并聊天

```bash
# 启动模型（将其加载到 GPU VRAM 中）
curl -X POST http://localhost:1337/v1/models/start \
  -H "Content-Type: application/json" \\
  -d '{"model": "llama3.2:3b-gguf-q4-km"}'

# 发送你的第一条聊天请求
curl http://localhost:1337/v1/chat/completions \
  -H "Content-Type: application/json" \\
  -d '{
    "model": "llama3.2:3b-gguf-q4-km",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "你好！你能帮我做什么？"}
    ],
    "temperature": 0.7,
    "max_tokens": 512,
    "stream": false
  }'
```

***

## 配置

### 环境变量

| 变量                     | 默认值                   | 描述                 |
| ---------------------- | --------------------- | ------------------ |
| `JAN_API_HOST`         | `0.0.0.0`             | 绑定 API 服务器的主机      |
| `JAN_API_PORT`         | `1337`                | Jan Server API 端口  |
| `CORTEX_API_PORT`      | `39281`               | 内部 Cortex 引擎端口     |
| `CUDA_VISIBLE_DEVICES` | `all`                 | 要暴露哪些 GPU（逗号分隔的索引） |
| `JAN_DATA_FOLDER`      | `/root/jan`           | Jan 数据文件夹路径        |
| `CORTEX_MODELS_PATH`   | `/root/cortex/models` | 模型存储路径             |

### 多 GPU 配置

对于有多块 GPU 的服务器（例如 Clore.ai 上的 2× RTX 3090）：

```yaml
environment:
  - CUDA_VISIBLE_DEVICES=0,1  # 使用两块 GPU
```

或者要专门指定某些 GPU：

```bash
# 仅在 GPU 0 上运行 Jan Server
docker run -d \\
  --name jan-server \
  --gpus '"device=0"' \
  -p 1337:1337 \
  -v jan-data:/root/jan \
  -v jan-models:/root/cortex/models \
  ghcr.io/janhq/cortex:latest
```

### 自定义模型配置

```bash
# 列出所有已拉取的模型
curl http://localhost:1337/v1/models | jq '.data[].id'

# 获取模型详情
curl http://localhost:1337/v1/models/llama3.2:3b-gguf-q4-km

# 停止正在运行的模型（释放 VRAM）
curl -X POST http://localhost:1337/v1/models/stop \
  -H "Content-Type: application/json" \\
  -d '{"model": "llama3.2:3b-gguf-q4-km"}'

# 删除模型（释放磁盘空间）
curl -X DELETE http://localhost:1337/v1/models/llama3.2:3b-gguf-q4-km
```

### 使用令牌保护 API

Jan Server 默认不包含身份验证。请使用 Nginx 作为反向代理：

```bash
apt-get install -y nginx apache2-utils

# 创建密码文件
htpasswd -c /etc/nginx/.htpasswd admin

# 配置 Nginx
cat > /etc/nginx/sites-available/jan-server << 'EOF'
server {
    listen 80;
    server_name _;

    location / {
        auth_basic "Jan Server";
        auth_basic_user_file /etc/nginx/.htpasswd;
        proxy_pass http://127.0.0.1:1337;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 300s;
    }
}
EOF

ln -s /etc/nginx/sites-available/jan-server /etc/nginx/sites-enabled/
nginx -t && systemctl restart nginx
```

***

## GPU 加速

### 验证 CUDA 加速

Jan Server 的 Cortex 引擎会自动检测 CUDA。验证它是否正在使用 GPU：

```bash
# 在加载模型后检查 GPU 显存使用情况
nvidia-smi

# 应显示 cortex 进程正在消耗 VRAM
# 示例输出：
# | Processes:                                                            |
# |  GPU   GI   CI        PID   Type   Process name            GPU Memory |
# |    0    N/A  N/A    12345    C   /usr/local/bin/cortex    8192MiB |
```

### 切换推理后端

Cortex 支持多个后端：

```bash
# 检查容器内可用的后端
docker exec jan-server cortex engines list

# 为 NVIDIA GPU 使用 TensorRT-LLM 后端（更快，但需要更多配置）
docker exec jan-server cortex engines install tensorrt-llm

# 使用 llama.cpp 后端（默认，兼容性最好）
docker exec jan-server cortex engines install llama-cpp
```

### 上下文窗口与批大小调优

```bash
# 自定义模型参数以优化 GPU 性能
curl -X POST http://localhost:1337/v1/models/start \
  -H "Content-Type: application/json" \\
  -d '{
    "model": "llama3.2:3b-gguf-q4-km",
    "ctx_len": 8192,
    "ngl": 99,
    "n_batch": 512,
    "n_parallel": 4,
    "cpu_threads": 8
  }'
```

| 参数           | 描述                    | 建议                          |
| ------------ | --------------------- | --------------------------- |
| `ngl`        | GPU 层数（越高 = 使用更多 GPU） | 设置为 `99` 以将 GPU 用满          |
| `ctx_len`    | 上下文窗口大小               | 根据 VRAM 而定，4096–32768       |
| `n_batch`    | 用于提示词处理的批大小           | RTX 3090 设为 512，更小的显卡设为 256 |
| `n_parallel` | 并发请求槽位                | API 服务器使用时为 4–8             |

***

## 提示与最佳实践

### 🎯 Clore.ai 预算的模型选择

```bash
# 预算档（$0.03–0.07/小时，RTX 3060 12GB）：
# 使用 7B 模型的 Q4_K_M 量化
curl -X POST http://localhost:1337/v1/models/pull \
  -d '{"model": "mistral:7b-instruct-v0.3-gguf-q4-km"}'

# 标准档（$0.07–0.21/小时，RTX 3090 24GB）：
# 使用 13B 模型的 Q5_K_M 量化，或 30B 的 Q4
curl -X POST http://localhost:1337/v1/models/pull \
  -d '{"model": "llama3.1:8b-instruct-gguf-q5-km"}'

# 高端档（[裸机](https://clore.ai/bare-metal)，A100 80GB）：
# 以高精度运行完整的 70B 模型
curl -X POST http://localhost:1337/v1/models/pull \
  -d '{"model": "llama3.3:70b-instruct-gguf-q4-km"}'
```

### 💾 持久化模型存储

由于 Clore.ai 实例是临时的，建议挂载外部存储：

```bash
# 使用命名卷（会随 Docker 保持）
docker compose down
# 模型会保存在名为 'jan-models' 的卷中

# 若要在不同实例之间实现真正持久化存储，
# 将模型上传到对象存储，并在启动时拉取：
cat > /workspace/startup.sh << 'EOF'
#!/bin/bash
docker compose up -d
sleep 30
# 预先拉取你经常使用的模型
curl -X POST http://localhost:1337/v1/models/pull \
  -H "Content-Type: application/json" \\
  -d '{"model": "mistral:7b-instruct-v0.3-gguf-q4-km"}'
EOF
chmod +x /workspace/startup.sh
```

### 🔗 将 Jan Server 作为 OpenAI 直替

```python
# Python —— 使用现有的 OpenAI 客户端库
from openai import OpenAI

client = OpenAI(
    base_url="http://<CLORE_IP>:1337/v1",
    api_key="not-required"  # Jan Server 默认没有认证
)

response = client.chat.completions.create(
    model="llama3.2:3b-gguf-q4-km",
    messages=[{"role": "user", "content": "解释量子计算"}],
    temperature=0.7
)
print(response.choices[0].message.content)
```

```bash
# 支持流式输出
curl http://localhost:1337/v1/chat/completions \
  -H "Content-Type: application/json" \\
  -d '{
    "model": "llama3.2:3b-gguf-q4-km",
    "messages": [{"role": "user", "content": "写一首关于 GPU 的俳句"}],
    "stream": true
  }'
```

### 📊 监控资源使用情况

```bash
# 实时查看 GPU 利用率
watch -n 1 nvidia-smi

# 查看容器资源使用情况
docker stats jan-server

# 查看详细日志
docker compose logs --tail=100 jan-server

# 查看模型加载时间
docker compose logs jan-server | grep -E "(loaded|started|error)"
```

***

## 故障排查

### 容器启动失败——未找到 GPU

```bash
# 验证 NVIDIA Docker 运行时已配置
docker info | grep -i nvidia

# 直接测试 GPU 访问
docker run --rm --gpus all nvidia/cuda:12.8.1-base-ubuntu22.04 nvidia-smi

# 如果这失败，请检查 Docker 守护进程配置
cat /etc/docker/daemon.json
# 应包含：{"runtimes": {"nvidia": {...}}}
```

### 模型下载卡住或失败

```bash
# 检查磁盘空间
df -h /root

# 检查容器日志中的错误
docker compose logs jan-server | tail -50

# 重新尝试拉取
curl -X POST http://localhost:1337/v1/models/pull \
  -H "Content-Type: application/json" \\
  -d '{"model": "mistral:7b-instruct-v0.3-gguf-q4-km"}'
```

### VRAM 不足（CUDA 内存不足）

```bash
# 检查当前 VRAM 使用情况
nvidia-smi --query-gpu=memory.used,memory.free --format=csv

# 先停止所有正在运行的模型
curl http://localhost:1337/v1/models | jq -r '.data[].id' | while read model; do
  curl -X POST http://localhost:1337/v1/models/stop \
    -H "Content-Type: application/json" \\
    -d "{\"model\": \"$model\"}"
done

# 使用量化更高的模型（Q3 或 Q4，而不是 Q8）
# Q4_K_M 通常只使用 Q8 所需 VRAM 的约 50%
```

### 无法从容器外连接到 API

```bash
# 确保端口 1337 绑定在所有接口上
docker ps --format "table {{.Names}}\t{{.Ports}}"
# 应显示：0.0.0.0:1337->1337/tcp

# 检查 Clore.ai 防火墙规则——在服务器设置中开放端口 1337
# 先在本地测试：
curl http://127.0.0.1:1337/health

# 然后从外部测试：
curl http://<CLORE_SERVER_IP>:<MAPPED_PORT>/health
```

### 推理缓慢（CPU 回退）

```bash
# 确认正在使用 CUDA（而不是 CPU）
docker exec jan-server cortex ps
# 应显示已分配 GPU 显存

# 在模型启动时强制使用 GPU 层
curl -X POST http://localhost:1337/v1/models/start \
  -H "Content-Type: application/json" \\
  -d '{"model": "mistral:7b-instruct-v0.3-gguf-q4-km", "ngl": 99}'
```

***

## 延伸阅读

* [Jan.ai 官方文档](https://jan.ai/docs) — 完整平台文档
* [Jan GitHub 仓库](https://github.com/janhq/jan) — 源代码与问题
* [Jan Server / Jan API](https://github.com/janhq/jan-server) — 服务器相关文档
* [Cortex.cpp 引擎](https://github.com/janhq/cortex.cpp) — 底层推理引擎
* [Clore.ai 入门指南](/guides/guides_v2-zh/ru-men-zhi-nan/getting-started.md) — 平台基础
* [GPU 比较指南](/guides/guides_v2-zh/ru-men-zhi-nan/gpu-comparison.md) — 选择合适的 GPU
* [在 Clore.ai 上运行 Ollama](/guides/guides_v2-zh/yu-yan-mo-xing/ollama.md) — 替代 LLM 服务器
* [在 Clore.ai 上运行 vLLM](/guides/guides_v2-zh/yu-yan-mo-xing/vllm.md) — 高吞吐推理服务器
* [Hugging Face 模型中心](https://huggingface.co/models?library=gguf) — 查找 GGUF 模型

> 💡 **成本提示：** Clore.ai 上的一块 RTX 3090（$0.07–0.21/小时）可以以 **约 50 tokens/秒** 运行 Llama 3.1 8B——足够个人使用或低流量 API。对于生产工作负载，考虑使用 vLLM（见 [vLLM 指南](/guides/guides_v2-zh/yu-yan-mo-xing/vllm.md)）部署在 A100 上。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-zh/ai-ping-tai-yu-zhi-neng-ti/jan.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.