当前位置：
  1. 首页
  2. AI人工智能
  3. 正文

[CoPaw 教程系列] #03: Copaw Models

AI人工智能 0 457

CoPaw 入门：模型配置详解

在 CoPaw 对话前，需要先配置模型。在控制台 → 设置 → 模型中可以快捷配置。

CoPaw 支持多种 LLM 提供商：

  • 云提供商（需 API Key）
  • 本地提供商（llama.cpp / MLX）
  • Ollama 提供商
  • LM Studio 提供商
  • 自定义提供商

本文将详细介绍这几类提供商的配置方式。

配置云提供商

云提供商（包括 ModelScope、DashScope、Aliyun Coding Plan、OpenAI 和 Azure OpenAI）通过 API 调用远程模型，需要配置 API Key。

支持的云提供商

  • ModelScope - 阿里云魔搭社区
  • DashScope - 阿里云灵积
  • Aliyun Coding Plan - 阿里云编码计划
  • OpenAI - GPT 系列
  • Azure OpenAI - 微软 Azure 版本

在控制台中配置

以 DashScope 为例：

  1. 打开控制台，进入 设置 → 模型
  2. 找到目标云提供商卡片（DashScope），点击 设置
  3. 输入你的 API key，点击 保存
  4. 保存后可以看到目标云提供商卡片右上角状态变成 可用
  5. 此时在上方的 LLM 配置 中：
  • 提供商 对应的下拉菜单中可以选择目标云提供商
  • 模型 对应的下拉菜单中出现一系列可选模型
  1. 选择目标模型（如 qwen3.5-plus），点击 保存
  2. 可以看到 LLM 配置栏右上角显示当前正在使用的模型提供商及模型

撤销授权

如果想撤销某个云提供商授权：

  1. 点击目标云提供商卡片的 设置
  2. 点击 撤销授权
  3. 二次确认撤销授权后，可将目标提供商的状态调整为 不可用

获取 API Key

ModelScope

  • 访问：https://modelscope.cn/
  • 登录后进入个人中心，创建 API Key

DashScope

  • 访问：https://dashscope.console.aliyun.com/
  • 登录后创建 API Key

OpenAI

  • 访问：https://platform.openai.com/api-keys
  • 登录后创建新的 API Key

Azure OpenAI

  • 在 Azure 门户中创建 OpenAI 资源
  • 在资源中获取 API Key 和端点

本地提供商（llama.cpp / MLX）

本地提供商在本地运行模型，无需 API Key

，数据不出本机。

前置条件

在 CoPaw 所在环境中安装对应后端：

# llama.cpp
pip install 'copaw[llamacpp]'


MLX（仅 macOS）


pip install 'copaw[mlx]'

下载模型

  1. 在控制台的模型页面可以找到 llama.cpp 和 MLX 对应的卡片
  2. 点击目标本地提供商（以 llama.cpp 为例）卡片的 模型
  3. 选择 下载模型
  4. 填写：
  • 仓库 ID（必填）—— 如 Qwen/Qwen3-4B-GGUF
  • 来源 —— Hugging Face（默认）或 ModelScope
  • 文件名（可选）—— 留空自动选择
  1. 点击 下载模型，可以看到正在下载模型，需要等待一段时间
  2. 模型下载完成后，可以看到本地提供商卡片右上角转为 可用 状态

选择模型

  1. 在上方的 LLM 配置 中：
  • 提供商 对应的下拉菜单中可以选择本地提供商
  • 模型 对应的下拉菜单中可选择刚刚添加的模型
  1. 点击 保存
  2. 可以看到 LLM 配置右上角显示本地提供商和选择的模型名称

管理已下载的模型

  • 点击对应本地提供商卡片上的 模型
  • 可以看到不同模型名称、大小、下载来源
  • 如果想删除模型，点击对应模型最右侧的 垃圾桶图标
  • 二次确认后即可删除

推荐模型

llama.cpp 推荐的 GGUF 格式模型：

  • Qwen/Qwen2.5-7B-Instruct-GGUF - 7B 指令微调模型
  • Qwen/Qwen2.5-14B-Instruct-GGUF - 14B 指令微调模型
  • mistralai/Mistral-7B-Instruct-v0.3-GGUF - Mistral 7B

MLX 推荐的模型（仅 macOS）：

  • mlx-community/Qwen2.5-7B-Instruct-MLX - 7B 模型
  • mlx-community/Qwen2.5-14B-Instruct-MLX - 14B 模型

性能优化建议

  1. 硬件要求
  • 7B 模型：至少 8GB RAM
  • 14B 模型：至少 16GB RAM
  • 推荐使用 GPU 加速（llama.cpp 支持 CUDA、Metal 等）
  1. 量化选择
  • Q4_K_M：平衡性能和质量（推荐）
  • Q5_K_M：质量更高
  • Q8_0：最高质量，但速度较慢
  1. 上下文长度
  • 必须设置为 32K 或以上
  • 在模型配置中调整 n_ctx 参数

Ollama 提供商

Ollama 提供商对接本机安装的 Ollama 守护进程，使用其中的模型，无需由 CoPaw 直接下载模型文件，列表会与 Ollama 自动同步。

前置条件

  1. 从 ollama.com 安装 Ollama
  2. 在 CoPaw 所在虚拟环境中安装 Ollama：
pip install 'copaw[ollama]'

下载模型

  1. 在控制台的模型界面中，可以看到 ollama 提供商对应的卡片
  2. 点击右下角 设置，在配置 ollama 的页面中，填写 API Key。
  • 此处可随意填写一个内容，例如 ollama
  • 点击 保存
  1. 点击 模型，如果已经使用 Ollama 下载过一些模型，则可以看到对应的模型列表
  2. 如果还没有下载模型，或需要下载额外模型，点击 下载模型
  3. 填写 模型名称，如：
  • mistral:7b
  • qwen2.5:7b
  • llama3:8b
  1. 点击 下载模型，可以看到进入模型下载状态，等待模型下载完成

选择模型

  1. 下载完成后，可以在上方的 LLM 配置 中：
  • 提供商 对应的下拉菜单中可以选择 Ollama
  • 模型 对应的下拉菜单中可选择想使用的模型
  1. 点击 保存
  2. 可以看到 LLM 配置右上角显示 Ollama 提供商和选择的模型名称

管理模型

  • 如果在过程中遇到 "Ollama SDK not installed. Install with: pip install 'copaw[ollama]'" 的提示，请先确认是否已经在 ollama.com 下载 Ollama，并在 CoPaw 所在虚拟环境中执行过 pip install 'copaw[ollama]'
  • 如果想删除某个模型，点击 Ollama 卡片右下角的 模型，在模型列表中，点击想要删除的模型右侧的 垃圾桶按钮，二次确认后即可删除

Docker 用户注意

如果 CoPaw 运行在 Docker 容器中，localhost 指向的是容器自身而非宿主机。请将 Ollama 的 Base URL 改为 http://host.docker.internal:11434（并在 docker run 命令中添加 --add-host=host.docker.internal:host-gateway

）。

推荐模型

Ollama 支持大量模型，推荐以下几款：

  • qwen2.5:7b - 阿里通义千问 7B
  • qwen2.5:14b - 阿里通义千问 14B
  • mistral:7b - Mistral 7B
  • llama3:8b - Meta Llama 3 8B
  • gemma2:9b - Google Gemma 2 9B

⚠️ 运行 CoPaw 前必须将上下文长度设为 32K 以上

为了正常运行 CoPaw，必须将模型 context length 设置为 32K 或更高

。注意，这会消耗较多的计算资源，请确保你的本地机器能够支持。

在 Ollama 中设置上下文长度的方法：

# 下载模型时指定上下文长度
ollama run qwen2.5:7b --num_ctx 32768


或在 Modelfile 中设置


FROM qwen2.5:7b
PARAMETER num_ctx 32768

LM Studio 提供商

LM Studio 提供商连接 LM Studio 桌面应用内置的 OpenAI 兼容服务器。模型在 LM Studio 的图形界面中管理，CoPaw 通过 /v1/models

端点自动发现已加载的模型。

前置条件

  1. 从 lmstudio.ai 安装 LM Studio
  2. 在 LM Studio 中加载模型并启动本地服务器（默认地址：http://localhost:1234）

配置步骤

  1. 在控制台的模型页面中，可以看到 LM Studio 提供商对应的卡片
  2. 点击右下角 设置，默认 Base URL 为 http://localhost:1234/v1。
  • 如果你在 LM Studio 中修改了端口，请相应调整
  • 点击 保存
  1. 点击 模型 查看 LM Studio 中当前已加载的模型
  • 如有需要，也可以手动添加模型 ID
  1. 在上方的 LLM 配置 中：
  • 提供商 下拉菜单中选择 LM Studio
  • 模型 下拉菜单中选择想使用的模型
  • 点击 保存

注意事项

  • LM Studio 默认不需要 API Key
  • 如果你 in LM Studio 中启用了认证功能，请在 API Key 字段中填入对应的密钥
  • 模型必须在 LM Studio 的图形界面中加载后才会在 CoPaw 中显示

Docker 用户注意

如果 CoPaw 运行在 Docker 容器中，localhost 指向的是容器自身而非宿主机。请将 LM Studio 的 Base URL 改为 http://host.docker.internal:1234/v1（并在 docker run 命令中添加 --add-host=host.docker.internal:host-gateway

）。

重要 — 上下文长度

LM Studio 加载模型时默认的上下文长度较小（通常为 2048 或 4096 tokens）。CoPaw 的系统提示词（AGENTS.md + SOUL.md + PROFILE.md）可能会超过此限制，导致报错：

"The number of tokens to keep from the initial prompt is greater than the context length"

解决方法：

在 LM Studio 中卸载模型，然后以更大的上下文长度重新加载（建议 16384 及以上）。

通过图形界面调整：

  1. 卸载模型
  2. 重新加载模型
  3. 在模型设置中调整 Context Length 为 32768 或更高

通过 CLI 操作：

lms unload --all && lms load <model> -c 16384

⚠️ 运行 CoPaw 前必须将上下文长度设为 32K 以上

为了正常运行 CoPaw，必须将模型 context length 设置为 32K 或更高

。注意，这会消耗较多的计算资源，请确保你的本地机器能够支持。

添加自定义提供商

除了内置的提供商外，CoPaw 还支持添加自定义提供商，适用于任何 OpenAI 兼容的 API。

配置步骤

  1. 在控制台的模型页面点击 添加提供商
  2. 填写 提供商 ID 和 显示名称，点击 创建
  3. 可以看见新添加的提供商卡片
  4. 点击 设置，填写：
  • Base URL - API 端点地址
  • API Key - 认证密钥
  • 点击 保存
  1. 可以看到自定义提供商卡片中已经显示刚刚配置的 Base_URL 和 API Key
  • 但此时右上角仍显示 不可用，还需要配置模型
  1. 点击 模型，填写 模型 ID，点击 添加模型
  2. 此时可见自定义提供商为 可用
  3. 在上方的 LLM 配置 中：
  • 提供商 对应的下拉菜单中可以选择自定义提供商
  • 模型 对应的下拉菜单中可选择刚刚添加的模型
  • 点击 保存
  1. 可以看到 LLM 配置右上角显示自定义提供商的 ID 和选择的模型名称

注意事项

  • 如果无法成功配置，请重点检查 Base URL、API Key 和 模型 ID 是否填写正确，尤其是模型的大小写
  • 如果想删除自定义提供商，在对应卡片右下角点击 删除提供商，二次确认后可成功删除

使用场景

自定义提供商适用于：

  • 使用第三方 OpenAI 兼容 API
  • 使用自建的 LLM 服务
  • 使用其他云服务商的 LLM（如 AWS Bedrock、Google Vertex AI 等）

模型选择建议

根据你的使用场景和硬件条件，选择合适的模型：

云提供商（推荐新手）

优点：

  • 无需本地硬件
  • 速度快
  • 模型质量高
  • 免去环境配置

推荐模型：

  • DashScope Qwen3.5-plus（中文友好）
  • OpenAI GPT-4o（综合能力最强）
  • ModelScope 通义千问系列

本地提供商（推荐有 GPU 的用户）

优点：

  • 数据完全本地
  • 无 API 费用
  • 隐私安全

缺点：

  • 需要强大的硬件
  • 速度较慢

推荐配置：

  • GPU：至少 8GB VRAM（7B 模型）
  • RAM：至少 16GB
  • 推荐：NVIDIA RTX 3060 或更高

Ollama（推荐 macOS 用户）

优点：

  • 安装简单
  • 模型丰富
  • 自动管理

推荐模型：

  • qwen2.5:7b - 平衡性能和质量
  • qwen2.5:14b - 更强的能力
  • llama3:8b - 英文场景

LM Studio（推荐 macOS/Windows 用户）

优点：

  • 图形界面友好
  • 模型管理方便
  • 支持多种格式

注意：

  • 必须设置 32K 以上上下文长度
  • 资源消耗较大

性能对比

| 提供商类型 | 速度 | 成本 | 隐私 | 难度 |

|-----------|------|------|------|------|

| 云提供商 | ⭐⭐⭐⭐⭐ | $$$ | ⭐⭐ | ⭐ |

| 本地提供商 | ⭐⭐ | Free | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |

| Ollama | ⭐⭐⭐ | Free | ⭐⭐⭐⭐⭐ | ⭐⭐ |

| LM Studio | ⭐⭐⭐ | Free | ⭐⭐⭐⭐⭐ | ⭐⭐ |

常见问题

Q1: 为什么本地模型报错上下文长度不足？

A: CoPaw 的系统提示词较长，需要至少 32K 的上下文长度。请在模型配置中设置 num_ctx 或 n_ctx

参数为 32768 或更高。

Q2: 如何切换模型？

A: 在控制台的 设置 → 模型 中，选择新的提供商和模型，点击 保存

即可。切换是即时生效的。

Q3: 能同时使用多个模型吗？

A: CoPaw 当前只支持一个活跃模型。但你可以随时在控制台中切换。

Q4: 本地模型太慢怎么办？

A: 考虑：

  1. 使用量化模型（Q4_K_M）
  2. 升级硬件（GPU）
  3. 切换到云提供商

Q5: Docker 中无法连接 Ollama/LM Studio？

A: 使用 host.docker.internal 代替 localhost，并确保在 docker run 时添加 --add-host=host.docker.internal:host-gateway

。

下一步

现在你已经了解了 CoPaw 支持的各种模型提供商及其配置方法。接下来建议：

  1. 阅读下一篇：CoPaw 入门：频道配置与接入 - 学习如何配置钉钉、飞书等频道
  2. 选择并配置模型：根据你的需求选择合适的提供商并配置模型
  3. 测试模型：在控制台的聊天界面测试模型是否正常工作
  4. 接入频道：配置频道后开始与 CoPaw 对话

总结

CoPaw 支持多种 LLM 提供商，满足不同用户的需求：

✅ 云提供商

- 快速、便捷、无需硬件

✅ 本地提供商

- 隐私、免费、数据本地

✅ Ollama

- 简单易用、模型丰富

✅ LM Studio

- 图形界面、易于管理

✅ 自定义提供商

- 灵活、支持任何 OpenAI 兼容 API

选择适合你的模型提供商，配置后即可开始使用 CoPaw。

相关资源

：

  • CoPaw 官方文档：https://copaw.agentscope.io/
  • CoPaw 模型文档：https://copaw.agentscope.io/docs/models
  • CoPaw 配置文档：https://copaw.agentscope.io/docs/config
  • Ollama 官网：https://ollama.com/
  • LM Studio 官网：https://lmstudio.ai/
上一篇 [CoPaw 教程系列] #02: Copaw Console
下一篇 [CoPaw 教程系列] #04: Copaw Channels

相关文章

发表回复

后才能评论