Discourse AI 插件具有许多需要启用大语言模型（LLM）的功能，包括摘要生成、AI Helper、语义搜索、AI Bot 及其代理。你可以使用第三方 API，例如 配置 OpenAI API 密钥 或 配置 Anthropic API 密钥，但 Discourse AI 从第一天起就设计为不依赖于这些服务。
本指南将介绍如何自行运行开源权重模型并将其连接到 Discourse。
此处使用的模型： Qwen/Qwen3.8-27B —— 一款于 2026 年 8 月发布的 27B 稠密模型，具有原生 256K 上下文窗口、图像/视频理解、工具调用功能，并默认启用思维模式。它目前是自建托管的最佳选择：功能足够强大，可用于真实的摘要/代理工作，规模又足够小，可以在单块 GPU 上运行。你可以替换为任何其他喜欢的模型；下文将指出需要更改的参数。
Discourse 对你的推理服务器有什么要求
- 一个 兼容 OpenAI 的
POST /v1/chat/completions端点（支持流式传输）。 - 如果你想让 AI Bot、代理或结构化输出良好运行，需要原生的工具/函数调用功能。如果没有此功能，Discourse 会回退到基于 XML 的工具调用，较弱模型对此处理不佳。
- 真正的上下文窗口 —— 目标至少 16K tokens，建议 32K+。Discourse 用于摘要和 RAG 的提示大小增长很快。
- 可选：图像输入，如果你希望模型读取帖子中附带的图像。
只要满足前三项要求的任何方案均可行，因此以下选择主要取决于你的硬件。
| 设置 | 适用场景 |
|---|---|
| vLLM | 专用 GPU 服务器，显存 ≥24GB（量化）/ 80GB（全精度），持续流量，多用户环境 |
| llama.cpp | 消费级 GPU，Apple Silicon，纯 CPU 机器，小型个人论坛 |
| 托管 / 云服务 | 你希望模型不运行在你的笔记本电脑上，也不运行在你的硬件上：任何兼容 OpenAI 的端点 |
使用 vLLM 运行
vLLM 是 GPU 服务器的推荐引擎：采用 Apache 许可证，开箱即用的兼容 OpenAI 服务器，并对 Qwen 系列提供一流支持。
mkdir -p /opt/vllm-cache
export VLLM_API_KEY="$(openssl rand -hex 24)"
docker run -d --name vllm \
--runtime nvidia --gpus all \
-v /opt/vllm-cache:/root/.cache/huggingface \
-e HF_HOME=/root/.cache/huggingface \
-e "HF_TOKEN=${HF_TOKEN}" \
-p 8080:8000 \
--ipc=host \
vllm/vllm-openai:latest \
Qwen/Qwen3.8-27B \
--host 0.0.0.0 \
--port 8000 \
--max-model-len 32768 \
--reasoning-parser qwen3 \
--enable-auto-tool-choice \
--tool-call-parser qwen3_xml \
--api-key "$VLLM_API_KEY"
关于这些参数的说明：
--max-model-len限制提示+输出的上下文长度，从而影响 KV 缓存。该模型原生支持 256K；32K 对于论坛任务已经绰绰有余，并且能保持显存使用可预测。如果你有足够内存，可以提高该值（或使用auto）。--reasoning-parser qwen3将模型的思维过程拆分到一个单独的reasoning字段中，而不是直接混入答案。你必须在此后的 Discourse LLM 设置中反映这一选择（见下文）。--enable-auto-tool-choice --tool-call-parser ...开启原生函数调用。解析器名称在不同 vLLM 版本间可能会变动 —— 如果工具调用返回的是纯文本，请在你的镜像内检查python3 -m vllm.entrypoints.openai.api_server --help。HF_TOKEN仅在使用受限模型时需要；--api-key用于保护你自己的端点。vLLM 文档中的警告：--api-key仅保护/v1路由，因此仍应将服务器置于公网之外。- 显存紧张？在缩减上下文之前，先尝试
--quantization fp8（或使用预量化 AWQ 检查点）。多 GPU：添加--tensor-parallel-size N。
测试它：
curl http://localhost:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $VLLM_API_KEY" \
-d '{
"model": "Qwen/Qwen3.8-27B",
"messages": [{"role": "user", "content": "What is Discourse?"}],
"max_tokens": 200
}'
你应该会收到一个正常的 chat-completion JSON 响应体，其中 message.content 旁边会有 message.reasoning。
使用 llama.cpp 运行
当模型需要适应比 vLLM 要求更少的显存，或者你使用 Apple Silicon、AMD、Vulkan 或 CPU 时，llama.cpp 是合适的工具。其 llama-server 也提供了兼容 OpenAI 的 API。
使用对应后端的容器镜像拉取并运行官方 GGUF 构建版本（这里使用 server-cuda；也存在 server、server-rocm、server-vulkan 等）：
export LLAMA_API_KEY="$(openssl rand -hex 24)"
docker run -d --name llama-server \
--gpus all \
-p 8080:8080 \
-v /opt/llama-models:/models \
ghcr.io/ggml-org/llama.cpp:server-cuda \
-hf ggml-org/Qwen3.8-27B-GGUF:Q4_K_M \
--host 0.0.0.0 \
--port 8080 \
--alias qwen3.8-27b \
--api-key "$LLAMA_API_KEY" \
--ctx-size 16384 \
--n-gpu-layers auto \
--flash-attn auto \
--jinja \
--reasoning auto
Q4_K_M权重约占 16GB；在 8K 上下文下测得约 18.4 GiB 显存，32K 时约 20 GiB，因此 24GB 显卡配合适中的--ctx-size是可以运行的。Unsloth 的unsloth/Qwen3.8-27B-GGUF:UD-Q4_K_M是一个流行的替代方案。--jinja使用模型自带的聊天模板 —— 这是实现原生工具调用工作的关键。--alias设置 API 报告的名称，以便你在 Discourse 中输入的模型名称与之匹配。--reasoning auto单独报告思维过程，匹配 vLLM 的--reasoning-parser行为。- 图像输入需要多模态投影器；使用
-hf时通常会自动获取，否则请传递--mmproj /models/mmproj-...gguf（或使用--no-mmproj以节省纯文本服务时的显存）。
测试它：
curl http://localhost:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $LLAMA_API_KEY" \
-d '{
"model": "qwen3.8-27b",
"messages": [{"role": "user", "content": "What is Discourse?"}],
"max_tokens": 200
}'
运行其他服务
任何支持 OpenAI chat completions 的服务器 —— 如 SGLang、TensorRT-LLM、LM Studio、企业网关、专用云部署 —— 均可直接使用：在 Discourse 中使用 vLLM 提供程序进行配置，这是一个支持原生工具调用的通用 OpenAI 兼容客户端。
如果你不想自己运行推理，但仍希望避免被大型 API 锁定，Hugging Face Inference Endpoints（现在默认使用 vLLM 作为引擎）可以与 Hugging Face 提供程序配合使用 —— 将其指向端点的 /v1/chat/completions URL。
让你的 Discourse 实例能够访问它
由于 GPU 需求，你通常会在专用机器上运行它。这样做时：
- 在服务器前设置一个反向代理并在其上终止 TLS —— Discourse 可以安全地通过 HTTPS 与其通信。
- 通过防火墙或客户端证书限制端点，以便只有你的 Discourse 主机可以连接。API 密钥用于身份验证，而不是网络边界。
- 将模型缓存保存在持久卷上，以便重启时不会重新下载数十 GB 的数据。
配置 Discourse AI
LLM 连接是通过管理界面而非站点设置进行配置的。前往 /admin/plugins/discourse-ai/ai-llms 并添加一个新的 LLM：
- 显示名称 —— 管理员和用户看到的名称。
- 名称 —— 在 API 请求中发送；它必须与服务器预期的名称匹配（vLLM 为
Qwen/Qwen3.8-27B，llama.cpp 为你的--alias）。 - 提供程序 —— 对于 vLLM、llama.cpp 和任何其他 OpenAI 兼容服务器选择 vLLM；对于托管在 HF 上的端点选择 Hugging Face。
- URL —— 包含路径的完整端点 URL，例如
https://llm.example.com/v1/chat/completions。 - API 密钥 —— 手动输入，或引用 AI Secrets 页面中存储的密钥。
- Tokenizer —— 对于 Qwen3.8 选择 Qwen（选择匹配你模型家族的分词器）。
- 最大提示 tokens / 最大输出 tokens —— 保持总和小于或等于你服务器的
--max-model-len/--ctx-size。例如，对于 32768 token 的服务器：28000 提示和 4096 输出。推理模型会将部分输出预算用于思考，因此不要挤压得太紧。 - Vision —— 如果你在提供服务时支持图像并希望模型读取图像，请启用原生视觉功能。
- 提供程序选项（vLLM）：将 vLLM reasoning parser 设置为
qwen3以匹配服务器参数，如果你希望 Discourse 按请求控制思维过程，请使用思维覆盖/推理力度/思维 token 预算字段。除非模型的功能调用出错，否则请保留“禁用原生工具”未选中状态。
点击运行测试后再保存：它会发出流式和非流式请求，并告诉你哪个失败了。
保存后，通过 ai_default_llm_model 站点设置将其设为站点默认值，或在 /admin/plugins/discourse-ai/ai-features 中按功能分配。单独的代理在 Agents 页面配置。
一个注意事项：语义搜索嵌入并非来自此模型。 嵌入使用其自己的嵌入模型，单独配置（API 嵌入模型，或通过 ai_hugging_face_tei_endpoint 设置配置的自托管 Text Embeddings Inference 服务器）。如果你希望完全自建托管 AI 搜索，请在你的 LLM 旁边运行一个小的嵌入模型，如 bge-m3。
故障排除
| 症状 | 可能原因 |
|---|---|
端点返回 404 |
URL 缺少 /v1/chat/completions |
model not found |
名称 与提供的模型 ID / --alias 不匹配 |
401 / 403 |
--api-key 和 LLM 记录之间的 API 密钥不匹配 |
| 帖子中出现 JSON 文本形式的工具调用 | 服务器启动时未进行工具调用解析；Discourse 回退到了 XML 工具 |
| 思维文本泄漏到答案中 | 服务器缺少 --reasoning-parser，或者 Discourse reasoning parser 设置与其不匹配 |
| CUDA 内存不足 | 降低 --max-model-len，添加 --quantization fp8，或降低 --gpu-memory-utilization |
| 长摘要请求超时 | 推理模型速度慢；我们的 HTTP 超时时间为 6 分钟 —— 减少上下文，降低思维力度，或禁用思维 |
| 答案被截断 | 一旦计入思维 tokens，Discourse 中的 max output tokens 太小 |
