# 配置参考

区分应用地址、模型服务、内部凭据、数据持久化与文档站设置，并明确可选能力的启用条件。

## 项目运行时

仓库根目录 .env.example 给出直接在本机启动服务的示例地址，Compose 使用容器服务名连接；配置类也可能包含容器网络默认值。因此应按实际启动方式填写地址，不能把 127.0.0.1 示例直接当作容器间地址。浏览器访问地址、服务内部地址和模型提供商地址分别配置。

| 配置 | 用途与当前行为 |
| --- | --- |
| IGRAPH_ADMIN_USER_ID | 默认 admin，指定单用户工作区的固定归属；自动建立默认记录，无需预先创建用户。升级时保持一致以复用历史数据 |
| FRONTEND_BIND_ADDRESS / FRONTEND_PORT | Compose 默认 127.0.0.1 / 21108；远程使用通过 SSH 隧道或受控访问入口 |
| AGENT_RUNTIME_AUTHORIZATION | 示例为 false；这是运行框架的授权开关，不会取消内部服务密钥或数据范围检查 |
| BACKEND_PORT / AGENT_RUNTIME_PORT | 本机示例为 21109 / 21112；分别监听公共 API 和运行服务 |
| AGENT_RUNTIME_URL | Backend 访问运行服务；本机示例 http://127.0.0.1:21112，配置默认 http://agent-runtime:21112 |
| GRAPH_ENGINE_URL | Backend 访问图 API；本机示例 http://127.0.0.1:21111，默认回退为 http://graph-engine-api:21111 |
| GRAPH_ENGINE_MCP_URL | 运行服务发现和调用图工具；本机示例 http://127.0.0.1:21110/mcp，可回退 MCP_SERVER_URL |
| BACKEND_CONTROL_URL / GRAPH_ENGINE_API_URL | 内部执行控制访问地址，不是模型服务地址 |
| AGENT_RUNTIME_DATABASE_URL | AgentOS PostgreSQL；本机示例主机 127.0.0.1，配置默认主机 postgres |
| IGRAPH_CONTROL_SERVICE_KEY | 完整部署必填；Backend、运行服务、图 API 与 MCP 使用同一随机非空、无空白 ASCII 凭据；取消关闭时仍需配置 |
| IGRAPH_RUN_CANCEL_ENABLED | .env.example 为 true；未设置时回退 false。统一启用并通过跨服务能力检查后，/api/capabilities 才开放停止入口 |
| VITE_API_BASE | 浏览器访问 Backend 的可选基础地址，默认空字符串使用同源 /api；构建前端时读取 |
| VITE_SESSION_STATE_V2 | 前端默认启用；显式设为 false 关闭对应 v2 状态处理 |
| BACKEND_STREAM_HEARTBEAT_SECONDS | SSE 空闲心跳，默认 15 秒 |
| AGENT_RUNTIME_JOB_POLL_INTERVAL_SECONDS / AGENT_RUNTIME_JOB_WAIT_TIMEOUT_SECONDS | 作业查询间隔默认 2 秒；等待上限默认 0，表示工具层不另设上限，仍受上游 HTTP 超时影响 |

开发前端的 Vite 服务默认监听 21108，并把 /api 代理到 http://127.0.0.1:21109。Compose 的前端通过自己的反向代理连接 Backend。远端部署时，VITE_API_BASE 若设置为浏览器无法访问的容器主机名，会导致请求失败；采用同源反向代理时可保持默认空值。

| 模型与学习配置 | 用途与区别 |
| --- | --- |
| LLM_API_KEY / LLM_BASE_URL | 模型调用的通用凭据与 OpenAI 兼容服务地址；按所选模型解析供应商配置 |
| OPENAI_* / CLAUDE_* / ANTHROPIC_* / QWEN_* / DEEPSEEK_* / ARK_* | 供应商模型连接配置，按 .env.example 和实际模型协议填写；也可在“模型服务”中维护提供商、凭据和可用模型 |
| IGRAPH_DEFAULT_MODEL | 运行服务后备默认模型为 qwen3.6-plus；当前工作区默认模型与可用列表以 GET /api/models 返回为准 |
| EMBEDDING_MODEL | 默认 text-embedding-3-small；用于可复用知识检索，不是对话模型 |
| EMBEDDING_API_KEY / EMBEDDING_BASE_URL | 显式值覆盖嵌入服务设置；未设置时分别回退到 OPENAI、LLM、QWEN 的对应变量 |
| AGENT_RUNTIME_SKILLS_ROOT | 技能目录；默认位于 IGRAPH_DATA_ROOT/agent_runtime/skills |
| AGENT_RUNTIME_TRACING / AGNO_TELEMETRY | 默认 true / false；运行追踪与遥测为不同开关 |

“模型服务”管理提供商连接与模型目录，公共入口包括 /api/model-providers、/api/models 和 /api/models/custom。URL 和 API Key 输入框打开时留空；留空保存会保留已有连接，填写新值后保存才替换，清除密钥需显式选择对应操作。Base URL 是模型提供商接口，不是 iGraph 工作台网址。嵌入模型仍需供应商实际支持；凭据只保存在应用配置中，不进入文档站。

| 工作区配置 | 用途与当前行为 |
| --- | --- |
| IGRAPH_DATA_ROOT / IGRAPH_WORKSPACE_ROOT | 数据根目录默认 data；会话工作区默认在其 workspaces 子目录，也可显式设置共享工作区根目录。Backend 与运行服务应访问同一持久存储。 |
| IGRAPH_WORKSPACE_SANDBOX_MODE | 默认 auto，要求可运行的 bubblewrap；不可用时启动检查失败。fallback 仅作为显式本地开发选项，受要求沙箱的环境限制。 |
| IGRAPH_WORKSPACE_EXEC_TIMEOUT_SECONDS / IGRAPH_WORKSPACE_OUTPUT_LIMIT | 工作区命令默认限时 30 秒、捕获输出预算 100000 字节；独立于图算法任务预算。 |

## 构图与计算

构图由 Graph Engine 运行，有独立的模型、预算与经验配置。下面的预算值来自 .env.example，供部署起步使用；单次请求支持的选项与边界以构图页面和同一部署的接口为准。关系型构图可显式使用 rules 基线，文本实体抽取需要可用的 LLM 服务。

| 配置 | 示例 / 默认行为 |
| --- | --- |
| GRAPH_CONSTRUCTION_MODE | 默认 llm；缺少模型配置会明确失败，rules 需显式选择 |
| GRAPH_CONSTRUCTION_MODEL / GRAPH_CONSTRUCTION_API_KEY / GRAPH_CONSTRUCTION_BASE_URL | 可单独指定构图模型与服务；未提供时按模型解析供应商配置 |
| GRAPH_CONSTRUCTION_QUERY_COUNT / GRAPH_CONSTRUCTION_MAX_ITERATIONS | 示例 15 / 6，控制查询集与迭代预算 |
| GRAPH_CONSTRUCTION_MAX_TOOL_CALLS / GRAPH_CONSTRUCTION_MAX_SECONDS | 示例 24 / 900，限制工具调用与总耗时 |
| GRAPH_CONSTRUCTION_BENCHMARK_REPEATS | 示例 3，基准测量重复次数 |
| GRAPH_CONSTRUCTION_CONCURRENCY | 示例 1，按 Graph Engine 进程限制；每用户同时一个构图任务 |
| GRAPH_CONSTRUCTION_EXPERIENCE_ENABLED / GRAPH_CONSTRUCTION_DOMAIN_CATEGORY | 默认 true / auto；复用同用户领域策略，每次仍在当前数据上验收 |
| GRAPH_COMPUTE_CONCURRENCY | 图计算进程池，默认 min(4, cpu_count) |
| AGENT_TOOL_MAX_CONCURRENCY | 单轮工具调度默认 4，限制在 1–32；与图计算进程池是不同设置 |
| GRAPH_HEAVY_PER_USER_CONCURRENCY | 训练、推理等重任务每用户默认 1 |
| LLM_TIMEOUT_SECONDS | 模型请求超时示例 180 秒 |
| MCP_ENABLE_REPORTING_TOOLS | 报告工具默认启用；false / off / 0 关闭 |

持久化部署还需保存 PostgreSQL、Graph Engine 数据、技能和会话工作区。大图计算、NebulaGraph、上传配额与文本抽取另有专门配置，不应仅调整一个构图超时来解决容量限制；按 .env.example、图计算文档和实际错误逐项核对。

分区大图采用持久化作业与工作进程，配置入口和普通图算法进程池不同。直接启动时 LARGE_GRAPH_EMBEDDED_WORKER 默认为 true；Compose 显式关闭内嵌工作进程，并启动独立 graph-engine-worker。准备阶段会把支持的文本边表或三元组转换为分区快照；并非所有二进制图格式都支持这条准备路径。

| 大图与数据入口配置 | 当前默认与用途 |
| --- | --- |
| LARGE_GRAPH_NODE_THRESHOLD / LARGE_GRAPH_EDGE_THRESHOLD | 默认 100 万节点 / 500 万边；达到任一阈值进入相应大图处理约束 |
| LARGE_GRAPH_UPLOAD_BYTES_THRESHOLD | 默认 256 MiB；支持的文本上传在全量读取前转入流式大图准备 |
| LARGE_GRAPH_BINARY_UPLOAD_BYTES_THRESHOLD | 默认 64 MiB；用于提前限制不能进入分区准备器的 npz / pt / json 等输入，避免全量反序列化 |
| LARGE_GRAPH_PARTITIONS | 示例 16；准备与分区计算使用的分区数 |
| LARGE_GRAPH_UPLOAD_MAX_BYTES / LARGE_GRAPH_USER_UPLOAD_QUOTA_BYTES | 图数据服务默认单文件 100 GiB、每用户 200 GiB；不是所有浏览器上传入口的统一上限 |
| IGRAPH_MAX_UPLOAD_BYTES | 聊天附件 Backend 入口默认 50 MiB；与图数据服务的大文件上限分开设置 |
| BACKEND_SERVER_DATASETS_DIR | 服务器预置数据目录；默认在数据根目录下的 server_datasets，Compose 可映射持久目录 |
| BACKEND_SERVER_DATASET_PREPROCESS_MIN_BYTES / BACKEND_SERVER_DATASET_SCAN_SECONDS | 文本边表预处理门槛默认 64 MiB，扫描周期默认 30 秒；门槛设为 0 可对所有文本边表启用预处理 |

- [图引擎与大图执行](/zh/graph-engine/): 了解准备、分区快照、工作进程及算法边界；完整调节项见仓库 .env.example。

构图页可选择模型或填写自定义模型 ID，并单独保存 URL、API Key，适用于 TXT 智能抽取与表格智能构图。GET /api/construction-models 返回模型列表，GET / POST /api/construction-model-settings 读取或保存连接。输入框留空时沿用已保存或服务器配置；显式清除才移除保存的密钥。Compose 默认将设置保存在 /data/configuration/construction-model.json，不写入数据集 options 或构图报告。

配置名中的 PER_USER、USER_UPLOAD_QUOTA 等仍按存储归属计数；在单用户版中，这些配额作用于默认工作区，不需要创建多个用户或设置登录权限。

## 文档站配置

独立文档站不使用模型 API Key、数据库连接、IGRAPH_CONTROL_SERVICE_KEY 或 VITE_API_BASE。docs-site/wrangler.jsonc 配置站点名称、兼容日期与 dist 静态资源目录。可选 SITE_URL 只在构建时生成绝对 canonical 和 sitemap，应为实际文档站的 HTTPS origin，不带路径、查询参数或片段。Cloudflare 发布凭据只用于发布静态文件，不是 iGraph 应用凭据。