配置说明

OpenMAIC 在服务器启动时读取环境变量。所有项都是可选的——按需启用。环境变量示例见仓库里的 .env.example。内置模型 ID 请见支持模型。

除环境变量外，也可以使用项目根目录下的 server-providers.yml 配置代码中已注册的服务端 provider。环境变量会逐字段覆盖 YAML 中的同名配置；自定义 OpenAI 兼容 provider 只能在设置中添加，不能通过任意环境变量前缀或未知 YAML provider ID 注册。

LLM 提供方

云端提供方通常使用以下三个环境变量：API key、base URL 和 model 列表。其中 API key 通常是必填的，base URL 和 model 列表可选；Azure OpenAI 需要配置资源 endpoint，Ollama 和 Lemonade 不需要 API key。

OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=                # 可选的 base URL 覆盖
OPENAI_MODELS=                  # 可选的模型白名单（逗号分隔）

支持的 provider 前缀：

Azure OpenAI 使用 deployment name 作为模型 ID：

AZURE_OPENAI_API_KEY=...
AZURE_OPENAI_BASE_URL=https://YOUR-RESOURCE.openai.azure.com/openai
AZURE_OPENAI_MODELS=your-deployment-name

Amazon Bedrock 通过 BEDROCK_REGION 启用，凭据走标准 AWS 环境变量 / 凭证链，不需要 OpenAI 风格的 API key（可选 BEDROCK_API_KEY）。

如需连接其他 OpenAI 兼容的 LLM 服务，请在 设置 → 模型提供方 中添加自定义 provider，并选择对应的协议类型。

本地模型（Ollama 和 Lemonade）

Ollama 和 Lemonade 不需要 API key；本地服务的 base URL 应写在服务端配置中，以通过 SSRF 校验：

OLLAMA_BASE_URL=http://localhost:11434/v1
# LEMONADE_BASE_URL=http://localhost:13305/v1

如需限制可用模型，可使用 OLLAMA_MODELS 或 LEMONADE_MODELS 指定模型白名单。

TTS 提供方

服务端 TTS 提供方使用 TTS_<PROVIDER>_API_KEY，可选 TTS_<PROVIDER>_BASE_URL。

# 豆包 TTS（火山引擎 Seed-TTS，原生 MP3）
TTS_DOUBAO_API_KEY=appId:accessKey
TTS_DOUBAO_BASE_URL=       # 可选覆盖

# Qwen TTS
TTS_QWEN_API_KEY=
TTS_QWEN_BASE_URL=         # 可选覆盖

# 任何 OpenAI 兼容的 TTS 端点
TTS_OPENAI_API_KEY=
TTS_OPENAI_BASE_URL=

# VoxCPM2（自托管 TTS，支持声音克隆，详见 VoxCPM2 单独页）
TTS_VOXCPM_BASE_URL=http://localhost:8000

支持的 TTS 前缀包括 TTS_OPENAI_、TTS_AZURE_、TTS_GLM_、TTS_QWEN_、TTS_MINIMAX_、TTS_DOUBAO_、TTS_ELEVENLABS_、TTS_VOXCPM_ 和 TTS_LEMONADE_。本地 Lemonade TTS 和 VoxCPM2 不需要 API key。浏览器原生 TTS 不需要服务端配置。

管理员可以使用 TTS_<PROVIDER>_ENABLED=false 在服务端强制关闭某个 TTS 提供方。VoxCPM2（自托管 TTS + 声音克隆）请见单独的 VoxCPM2 章节。

也可以在设置中添加自定义 OpenAI 兼容 TTS provider，填写 Base URL、模型和音色。这类自定义 provider 保存在客户端设置中，不通过任意 TTS_* 环境变量或 YAML provider ID 注册。

ASR（语音转文字）

# OpenAI Whisper
ASR_OPENAI_API_KEY=
ASR_OPENAI_BASE_URL=       # 可选覆盖

# Qwen ASR
ASR_QWEN_API_KEY=
ASR_QWEN_BASE_URL=         # 可选覆盖

# Azure ASR
ASR_AZURE_API_KEY=
ASR_AZURE_BASE_URL=https://{region}.api.cognitive.microsoft.com

# FunASR（本地，不需要 key）
ASR_FUNASR_BASE_URL=http://localhost:8000/v1

# Lemonade ASR（本地，不需要 key）
ASR_LEMONADE_BASE_URL=http://localhost:13305/v1

使用 funasr-server --device cuda 启动 OpenAI 兼容服务。它在 /v1/audio/transcriptions 接收 WAV，并可在模型选择器中使用 SenseVoiceSmall、Paraformer 和 Fun-ASR-Nano。

浏览器原生 ASR 不需要服务端配置。

也可以在设置中添加自定义 OpenAI 兼容 ASR provider，填写 Base URL、模型和支持语言；该配置保存在客户端设置中。

图像生成提供方

图像生成提供方使用 IMAGE_<PROVIDER>_API_KEY，可选 IMAGE_<PROVIDER>_BASE_URL。支持的前缀包括：

IMAGE_OPENAI_、IMAGE_SEEDREAM_、IMAGE_QWEN_IMAGE_、IMAGE_NANO_BANANA_、IMAGE_MINIMAX_、IMAGE_GROK_ 和 IMAGE_LEMONADE_。

Lemonade 是本地服务，不需要 key：

IMAGE_LEMONADE_BASE_URL=http://localhost:13305/v1

ComfyUI Image 不需要 API key，默认连接 http://localhost:8188。在设置中填写 ComfyUI Base URL，并把以 API 格式导出的 workflow JSON 放入 OpenMAIC 的 public/ 目录；文件名使用 comfyui-*.json 或包含 workflow，设置页会自动发现这些文件并将其作为可选 workflow。Docker 部署时还需要在构建镜像前加入 workflow，或把单个 workflow 文件挂载到容器的 /app/public/ 目录。由于 comfyui-image 不是服务端托管 provider，生产环境连接宿主机 ComfyUI 时还需要设置 ALLOW_LOCAL_NETWORKS=true。

视频生成提供方

视频生成提供方使用 VIDEO_<PROVIDER>_API_KEY，可选 VIDEO_<PROVIDER>_BASE_URL。支持的前缀包括：

VIDEO_SEEDANCE_、VIDEO_KLING_、VIDEO_VEO_、VIDEO_MINIMAX_、VIDEO_GROK_ 和 VIDEO_HAPPYHORSE_。

文档和媒体解析

课程材料的具体格式取决于所选解析器。当前支持文本、PDF、Office 文档、图片以及部分音视频格式；不同 provider 支持的格式和能力不同。

# MinerU 自托管
PDF_MINERU_BASE_URL=http://localhost:8888

# MinerU 自托管的可选后端
PDF_MINERU_BACKEND=pipeline

# MinerU Cloud
PDF_MINERU_CLOUD_API_KEY=
PDF_MINERU_CLOUD_BASE_URL=https://mineru.net/api/v4

# AliDocMind（使用阿里云 AccessKey，而不是单独的 API key）
ALIDOCMIND_ACCESS_KEY_ID=
ALIDOCMIND_ACCESS_KEY_SECRET=
ALIDOCMIND_BASE_URL=       # 可选覆盖

unpdf 内置于 OpenMAIC，可用于基础 PDF 解析。Office 文档、图片和需要 OCR、表格、公式或版面分析的材料，应选择兼容的 MinerU 或 AliDocMind provider。

AliDocMind 的文档解析支持 PDF、DOCX、PPTX、XLSX，以及 PNG、JPG/JPEG、BMP、GIF。当前音视频材料仅支持通过 AliDocMind 解析：视频格式为 MP4、MOV、AVI、MKV、WMV，音频格式为 MP3、WAV、AAC；不支持 M4A。

本地音视频提取： OpenMAIC 可以在本地提取带时间戳的转写和整理好的视频关键帧。安装系统 ffmpeg 包（让 ffmpeg 和 ffprobe 在 PATH 上可执行），并配置一个服务端 ASR provider（如 FunASR、Lemonade 或 OpenAI）。可执行文件在提取时解析；ffmpeg 不是 npm 依赖，启动或使用 OpenMAIC 都不需要它。若可执行文件不可用，本地提取会被跳过，已配置的 AliDocMind 仍是云端提取路径；两者都不可用时，音视频材料会以可操作的提示标记失败，而不是挂起或产出空转写。

联网搜索

配置 Tavily、Bocha、Brave、Baidu、SearXNG、MiniMax、豆包或 Claude：

TAVILY_API_KEY=
TAVILY_BASE_URL=           # 可选覆盖

BOCHA_API_KEY=
BOCHA_BASE_URL=            # 可选覆盖

BAIDU_API_KEY=
BAIDU_BASE_URL=https://qianfan.baidubce.com  # 可选覆盖

# 自托管 SearXNG，不需要 API key
SEARXNG_BASE_URL=

WEB_SEARCH_MINIMAX_API_KEY=
WEB_SEARCH_MINIMAX_BASE_URL=https://api.minimaxi.com  # 可选覆盖

# 豆包联网搜索（独立变量，避免与豆包 LLM provider 冲突）
WEB_SEARCH_DOUBAO_API_KEY=
WEB_SEARCH_DOUBAO_BASE_URL=https://open.feedcoopapi.com

# Claude（Anthropic）原生联网搜索
WEB_SEARCH_CLAUDE_API_KEY=
WEB_SEARCH_CLAUDE_BASE_URL=https://api.anthropic.com/v1

Brave 和 SearXNG 不需要 API key；前端可以在每次生成时选择是否启用搜索。Grok 的联网搜索通过 Grok LLM 的搜索工具提供，不是独立的联网搜索 provider。

ACCESS_CODE —— 站点级访问密码

对共享部署（内部 demo、课堂），可以设置访问码，访客先输密码才能看到应用：

ACCESS_CODE=your-secret-code

请使用足够长的随机值（至少 16 个字符），因为该密码是保护部署的唯一密钥。验证通过后会在 HTTP-only cookie 中保存一个签名令牌，有效期 7 天，由服务端强制校验，过期后需要重新验证。只有在受信任的反向代理之后设置 TRUST_PROXY_HEADERS=true（由代理覆盖 x-forwarded-for / x-real-ip）时才会限流：按客户端限流（每个客户端 60 秒内 10 次），验证成功会清空该客户端的计数；没有可信代理时应用无法把请求归因到具体客户端，因此完全不限流，保护依赖密码的长度和随机性。留空则关闭。

默认模型和模型路由

服务端 API 没有收到客户端模型时，需要通过 DEFAULT_MODEL 指定默认模型。模型写法是 provider:model-id，例如：

DEFAULT_MODEL=openai:gpt-5.5

可以使用 MODEL_ROUTES 为不同生成阶段指定模型；未配置的阶段继续按客户端模型和 DEFAULT_MODEL 解析。它是一个 JSON 对象，键为生成阶段，值可以是模型字符串，也可以是包含 model 和 thinking 的对象。完整的阶段列表和示例见仓库里的 .env.example。

功能开关

功能开关的值为 true 或 1；除非另有说明，其他值视为关闭。NEXT_PUBLIC_* 开关会在构建时注入客户端，修改后需要重新构建：

# MAIC Editor（Pro 模式）
# Pro 工作台入口（隐含下面的 MAIC Editor 开关；完整工作台还需服务端 Agent Runtime）
NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=true

NEXT_PUBLIC_MAIC_EDITOR_ENABLED=true

# Pi 对话运行时默认开启；取消下一行的注释可回滚到旧版链路
# NEXT_PUBLIC_PI_CHAT_ENABLED=false

# Pi 播放态中的 PPT 与互动页课件引用（构建时开关；不影响编辑态引用）
NEXT_PUBLIC_COURSEWARE_REFERENCE_ENABLED=true

# 职业教育任务引擎（服务端开关）
OPENMAIC_ENABLE_VOCATIONAL=true

# 显示职业教育实验开关
NEXT_PUBLIC_SHOW_VOCATIONAL_TEST_UI=true

# 显示视频导出入口
NEXT_PUBLIC_ENABLE_VIDEO_EXPORT=true

# 显示实验性 PPTX 导入入口
NEXT_PUBLIC_ENABLE_PPTX_IMPORT=true

Pi 对话运行时依赖模型的工具／函数调用能力。如果所选模型或 provider 不支持工具调用，请设置 NEXT_PUBLIC_PI_CHAT_ENABLED=false（或 0）并重新构建，以使用旧版对话链路。

使用 Docker Compose 时，.env.local 由 env_file 在运行时加载，不参与构建参数插值。请按下面的命令显式传入构建时配置并重新构建；只修改运行时环境不会改变已构建的客户端和服务端对话路径。

NEXT_PUBLIC_PI_CHAT_ENABLED=false docker compose up -d --build openmaic

PPTX 导入目前仍是实验性入口，解析结果尚未完整接入课堂数据流。以上 NEXT_PUBLIC_* 变量都是构建时开关；Docker 部署还需要通过 build args 传入，不能只写在容器运行时环境变量中。

Agent Runtime（实验性）——OPENMAIC_AGENT_RUNTIME_ENABLED=true 启用持久后台 Agent 会话（/api/agent/* 控制面 + 进程内会话 runner），关闭时这些路由返回 404。运行时必须有 DATABASE_URL（缺省则 runner 不启动、会话存储拒绝请求），且 MODEL_ROUTES 必须显式把 maic-agent-driver 阶段路由到带 provider 前缀的模型、api 设为 openai-completions 或 openai-responses——该阶段没有回退。Runner 的扫描间隔、心跳、租约 TTL、并发与重试参数见 .env.example。

其他服务端选项

以下服务端选项也可以通过环境变量配置：

# 场景内容并行生成；0 或未设置表示串行
PARALLEL_SCENE_CONCURRENCY=3

# 允许访问 localhost、内网等本地网络地址；仅用于自托管/内网部署
ALLOW_LOCAL_NETWORKS=true

# 可选的 MP4 渲染服务
RENDER_SERVICE_URL=http://render-service:9000

# 日志和推理
LOG_LEVEL=info
LOG_FORMAT=pretty
LLM_THINKING_DISABLED=false

用 YAML 配置文件

除了环境变量，你也可以把代码中已注册 provider 的配置放在项目根目录下的 server-providers.yml 文件里。服务端启动时加载，结构与环境变量分类对应：

providers:
  openai:
    apiKey: sk-...
    baseUrl: https://api.openai.com/v1
    models:
      - gpt-5.5
  anthropic:
    apiKey: sk-ant-...

tts:
  doubao-tts:
    apiKey: appId:accessKey

asr:
  openai-whisper:
    apiKey: sk-...

pdf:
  mineru:
    baseUrl: http://localhost:8888
  alidocmind:
    accessKeyId: your-access-key-id
    accessKeySecret: your-access-key-secret

image:
  seedream:
    apiKey: ...

video:
  seedance:
    apiKey: ...

web-search:
  tavily:
    apiKey: tvly-...
  searxng:
    baseUrl: http://localhost:8080

环境变量会逐字段覆盖 YAML 中的同名 provider 配置。键名必须使用代码中已注册的 provider ID，例如 openai、doubao-tts、openai-whisper、mineru、alidocmind、seedream、seedance、tavily 或 searxng；未知 ID 不能在这里注册为自定义 LLM provider。