配置

KaaS 使用单个 TOML 文件进行配置。本教程将带你了解最重要的配置项，以及如何根据你的环境进行定制。

配置文件

KaaS 从工作目录下的 etc/kaas.toml 读取配置。如果你通过 CLI 安装脚本安装，默认配置文件位于 ~/.local/share/kaas/etc/kaas.toml。

指定配置文件启动服务：

kaas serve -f /path/to/kaas.toml

配置文件按 section 组织：[llm]、[server]、[storage]、[worker]、[ai]、[ai.mcp] 等。下面按重要性依次介绍。

LLM 设置

这是最关键的配置 —— 它告诉 KaaS 使用哪个大语言模型来驱动知识编译流水线和对话。

[llm]
api_key = "sk-..."
base_url = "https://api.openai.com/v1"
model = "gpt-4o-mini"

KaaS 兼容任何 OpenAI 兼容 API。以下是常见提供商的配置示例：

OpenAI

[llm]
api_key = "sk-proj-xxxxx"
base_url = "https://api.openai.com/v1"
model = "gpt-4o-mini"

DeepSeek

[llm]
api_key = "sk-xxxxx"
base_url = "https://api.deepseek.com"
model = "deepseek-chat"

Ollama（本地部署）

[llm]
api_key = "ollama"          # Ollama 会忽略此字段，但不能留空
base_url = "http://localhost:11434/v1"
model = "llama3.1"

摘要模型

默认情况下，摘要步骤使用与主模型相同的模型。如果你想用更便宜/更快的模型做摘要，可以显式设置 summarize_model：

[llm]
model = "gpt-4o"
summarize_model = "gpt-4o-mini"

服务器设置

控制 HTTP 服务的监听地址：

[server]
host = "0.0.0.0"
port = 8080

大多数部署使用默认值即可。如果只需要本地访问且没有反向代理，可以将 host 改为 127.0.0.1。

存储

KaaS 将任务状态存入数据库，并将编译后的 Wiki 以 Markdown 文件输出：

[storage]
driver = "sqlite"
sqlite_path = "./data/kaas.db"
kb_dir = "./data"

字段	用途
driver	"sqlite"（默认）或 "mysql"
sqlite_path	SQLite 数据库文件路径
kb_dir	编译后 Wiki Markdown 文件的输出目录

kb_dir 就是你的知识库所在目录 —— MCP 客户端会指向这个目录，你也可以将它纳入 git 版本管理。

MySQL

如果需要多副本生产部署，可切换至 MySQL：

[storage]
driver = "mysql"
mysql_dsn = "user:pass@tcp(127.0.0.1:3306)/kaas"
kb_dir = "./data"

Worker 调优

Worker 配置控制编译流水线的并发度：

[worker]
extract_workers = 4
pipeline_concurrency = 2
poll_interval_ms = 1000
lease_timeout_sec = 300
cb_failure_threshold = 5
cb_cooldown_sec = 30

关键调优参数：

字段	默认值	何时调整
extract_workers	4	LLM 提供商允许更高并发时可增大
pipeline_concurrency	2	需要同时处理更多文档时可增大
cb_failure_threshold	5	熔断器 —— 连续 N 次 LLM 调用失败后触发熔断
cb_cooldown_sec	30	熔断触发后等待多久进入半开试探

WARNING

extract_workers 设得太高可能触发 LLM 提供商的速率限制。建议从默认值开始，逐步增加。

MCP 设置

KaaS 可以暴露 MCP (Model Context Protocol) 端点，让远程 AI Agent 查询你的知识库：

[ai.mcp]
enabled = false
token = ""
timeout_sec = 120

启用方法：

[ai.mcp]
enabled = true
token = "your-secret-token"    # 内网部署可留空
timeout_sec = 120

启用后，Agent 通过 http://<host>:8080/mcp 连接，携带 Authorization: Bearer your-secret-token。

# 示例：将 Claude Code 连接到远程 KaaS 实例
claude mcp add --transport http kaas http://your-server:8080/mcp

环境变量

每个 TOML 配置项都可以用环境变量覆盖。对于 Docker 部署和 CI/CD 流水线，推荐使用环境变量 —— 避免在配置文件中存放密钥。

环境变量	覆盖的配置项	默认值
LLM_API_KEY	[llm] api_key	（空）
LLM_BASE_URL	[llm] base_url	https://api.openai.com/v1
LLM_MODEL	[llm] model	gpt-4o-mini
LLM_SUMMARIZE_MODEL	[llm] summarize_model	同 model
KAAS_MCP_ENABLED	[ai.mcp] enabled	false
KAAS_MCP_TOKEN	[ai.mcp] token	（空）
KAAS_AI_MCP_URL	[ai] mcp_url	（空）

环境变量始终优先于 TOML 文件中的配置值。

Docker vs CLI

配置方式取决于你的部署方法：

Docker：使用环境变量

docker run -d --name kaas \
  -p 8080:8080 \
  -v ./data:/app/data \
  -e LLM_API_KEY=sk-xxx \
  -e LLM_BASE_URL=https://api.openai.com/v1 \
  -e LLM_MODEL=gpt-4o-mini \
  -e KAAS_MCP_ENABLED=true \
  -e KAAS_MCP_TOKEN=my-secret \
  kaas

这样可以避免密钥泄露到镜像层中，修改配置也很简单（用新环境变量重启容器即可）。

CLI：编辑 TOML 文件

# 编辑配置
vim etc/kaas.toml

# 使用指定配置启动
kaas serve -f etc/kaas.toml

也可以两者结合 —— TOML 文件存放非敏感的默认配置，环境变量传递密钥：

export LLM_API_KEY="sk-xxx"
kaas serve -f etc/kaas.toml

下一步

• 完整的逐字段配置参考，请查看配置参考
• 完整的环境变量列表，请查看环境变量
• 准备好处理你的第一批文档了？继续阅读构建你的第一个知识库