---
url: /v6.2/ai-general.md
---
# 模型通用配置

下列配置项为 Data Agent 系统级配置，按功能分为以下几类。

***

## 一、大模型 API 通用配置

与大模型 API 调用直接相关的核心参数。

### `LLM_MAX_TOKENS`

大模型最大输出 token 数，默认值是 1000。

### `LLM_API_TIMEOUT_SECONDS`

大模型 API 调用超时时间（秒），默认 600 秒。

### `LLM_API_SLEEP_INTERVAL`

在页面配置中是 `API 调用间隔 (秒)`。设定 API 请求之间的休眠间隔，以秒为单位。对于需要限制频率的大模型 API 可以考虑设置。

### `LLM_API_RETRY_NUM`

大模型 API 调用失败后的重试次数，默认值是 1。

### `LLM_ENABLE_SEED`

在页面配置中是 `使用 seed 参数`。控制是否在生成回复时启用随机种子，以带来结果的多样性。

### `LLM_API_SEED`

在页面配置中是 `seed 参数`。在生成回复时使用的随机种子数字。配合 `LLM_ENABLE_SEED` 使用。

### `USE_TEMPERATURE`

是否使用 temperature 参数，默认开启。部分模型不支持 temperature 参数，可以关闭。

### `USE_MAX_COMPLETION_TOKENS`

是否用 max_completion_tokens 替换 max_tokens 参数名称。默认关闭。GPT-5 以上的模型使用 max_completion_tokens 参数，需要开启。

### `LLM_API_REQUIRE_JSON_RESP`

是否要求大模型 API 返回 JSON 格式，默认关闭。

### `HISTORY_LIMIT`

在页面配置中是 `连续对话上下文条数`。与大模型交互时携带的历史对话条目数量，默认值是 4。

### `CHAT_WITH_NO_THINK_PROMPT`

大模型对话是否都加上 no think 的 prompt。对于阿里巴巴的 qwen3 系列模型有用，可以关闭思考，提高速度。对于智谱的 glm-4.5 以上模型，该开关也控制是否禁用思考。默认是 false，即开启思考。

### `THINKING_PARAM`

大模型思考参数配置，JSON 格式，用于控制不同模型的思考开关。支持多种模型的参数格式，例如：`{"thinking": {"type": "enabled"}}`（Anthropic Claude）、`{"enable_thinking": true}`（通义千问）、`{"reasoning_effort": "medium"}`（OpenAI o 系列）。配置后会自动合并到每次大模型 API 请求体中。

### AWS Bedrock 相关配置

#### `LLM_AWS_BEDROCK_REGION`

AWS Bedrock 区域。如果使用 AWS Bedrock 才需要配置。默认是 `ap-southeast-2`，具体请参考 AWS Bedrock 文档。

#### `LLM_ANTHROPIC_VERSION`

AWS Anthropic Claude 的版本号。如果使用 AWS Anthropic Claude 模型才需要配置。默认是 `bedrock-2023-05-31`。

### 代理配置

#### `ENABLE_LLM_API_PROXY`

是否开启大模型 API 代理，开启后可以通过衡石来调用大模型的 /chat/completions 接口。默认开启。Agent 模式也是通过衡石来调用大模型接口的。

#### `ENABLE_TENANT_LLM_API_PROXY`

租户是否可以使用大模型 API 代理，默认开启。Agent 模式也是通过衡石来调用大模型接口的。

***

## 二、向量数据库配置

向量搜索和向量化相关的配置。

### `ENABLE_VECTOR`

启用向量搜索功能。AI 助手通过大模型 API 来挑选跟问题最相关的例子。开启向量搜索后，AI 助手会综合大模型 API 和向量搜索的结果。

### `VECTOR_MODEL`

向量化模型。需要跟 `VECTOR_ENDPOINT` 配合使用。系统自带的向量服务已包含 `intfloat/multilingual-e5-base` 模型。如需其他模型，支持选择 Huggingface 上的向量模型，但需确保向量服务能连通 Huggingface 官网。

### `VECTOR_ENDPOINT`

向量化 API 地址。安装好向量数据库相关服务后，默认指向自带的向量服务。

### `VECTOR_SEARCH_RELATIVE_FUNCTIONS`

是否搜索问题相关的函数说明。开启后会搜索问题相关的函数说明，相应的提示词会变大。此开关只有在 `ENABLE_VECTOR` 开启时才生效。

### `VECTOR_SEARCH_FIELD_NUM_LIMIT`

向量搜索字段数量限制，默认值是 10。

### `VECTOR_SEARCH_FIELD_VALUE_NUM_LIMIT`

分词搜索数据集字段 distinct value 个数的上限，distinct value 匹配过多的部分将不会提取，默认值是 10。

### `VECTORIZE_DISTINCT_VALUES_LIMIT`

字段 distinct value 向量化数量限制，默认值是 10000。

### `VECTOR_MODEL_KEEP_COUNT`

当切换向量模型时，保留历史向量模型向量化数据的最大模型个数，默认是 5。

### `INIT_VECTOR_PARTITIONS_SIZE`

例子向量化分批执行每批大小，默认是 100。

### `INIT_VECTOR_INTERRUPTION_THRESHOLDS`

当向量化例子库时，最大允许失败个数，默认是 100。

### `CHAT_VECTOR_MATCH_SIMILARITY_THRESHOLD`

向量搜索相似度阈值，一般不用调整。默认值是 0.9。

### `CHAT_VECTOR_MATCH_WEIGHT`

向量搜索分数权重，一般不用调整。默认值是 0.15。

### `CHAT_TOKEN_MATCH_SIMILARITY_THRESHOLD`

文本搜索相似度阈值，一般不用调整。默认值是 0.01。

### `CHAT_TOKEN_MATCH_WEIGHT`

文本搜索分数权重，一般不用调整。默认值是 0.85。

### `AUTO_CLEAN_VECTOR_DB_ENABLE`

是否自动清理向量数据库，默认开启。

### `AUTO_CLEAN_VECTOR_DB_EXPIRE_DAYS`

向量数据库自动清理的过期天数，默认是 3 天。

***

## 三、UI 界面配置

前端展示和交互相关的配置。

### `CHAT_BEGIN_WITH_SUGGEST_QUESTION`

在去分析跳转后，是否会给用户提供几个推荐问题。根据需要开启。

### `CHAT_END_WITH_SUGGEST_QUESTION`

每个问题回合回答后，是否会给用户提供几个推荐问题。根据需要开启。关闭可以节省一部分时间。

### `TABLE_FLEX_ROWS`

设定对话中表格的最大可视范围行数，默认为 5。

### `EXPAND_AGENT_REASONING`

设定是否自动展开 Agent 思考过程，默认展开。

### `GRAPH_FIRST`

是否优先展示图表而非总结，默认关闭。

### `CHART_SOURCE_PRIMARY`

图表来源是否为主要展示，默认开启。

### `ENABLE_SMART_CHART_TYPE_DETECTION`

是否开启图表类型智能判断，默认为 true。如果需要图表类型全部为表格，可以关闭。图表类型判断规则：

* 1个时间维度和1个或多个度量：折线图
* 1个时间维度，1个文本维度，1个度量：面积图
* 1个文本维度和1个度量：柱状图
* 1个文本维度和2个度量：分组柱状图
* 其他默认使用表格

### `ENABLE_KPI_CHART_DETERMINE_BY_DATA`

是否根据 data 结果为 1 行 1 列数字修改图表类型为 KPI，默认是 true。如果需要图表类型全部为表格，可以关闭。

### `CHAT_DATA_DEFAULT_LIMIT`

AI 生成的图表，如果 AI 没有根据语义设置，默认 limit 是多少，默认 100。

### `PREFETCH_SOURCE_ON_ROUTE_CHANGE`

路由变化时是否预取资源，默认关闭。性能优化相关内部配置。

***

## 四、Workflow 功能配置

Workflow 模式特有的配置项。

### `LLM_SUGGEST_QUESTION_LOCALLY`

在页面配置中是 `不使用模型生成推荐问题`。指定是否在生成推荐问题时使用大模型。

* true：本地规则生成
* false：大模型生成

### `LLM_ANALYZE_RAW_DATA`

在页面配置中是 `允许模型分析原始数据`。设置 Data Agent 是否分析原始输入数据。若您的数据比较敏感，可以关闭此配置。

### `LLM_ANALYZE_RAW_DATA_LIMIT`

在页面配置中是 `允许分析的原始数据数量（行）`。设置分析原始数据的数量限制，默认值是 10。

### `LLM_SELECT_FIELDS_SHORTCUT`

此参数设置是否在字段比较少的时候不挑选字段，直接选择所有字段参与生成 HQL。配合 `LLM_SELECT_ALL_FIELDS_THRESHOLD` 使用。一般不需要设置为 true。对速度特别敏感或者想省掉字段选择步骤时可以设置。但不选择字段会影响最终数据查询的正确性。

### `LLM_SELECT_ALL_FIELDS_THRESHOLD`

在页面配置中是 `允许模型分析元信息 (阈值)`。设置选择所有字段的阈值，默认值是 50。`LLM_SELECT_FIELDS_SHORTCUT` 为 true 时此参数才有作用。

### `LLM_HQL_USE_MULTI_STEPS`

是否通过多个步骤来优化趋势、同环比类型问题的指令遵循程度。多个步骤会相对慢一些，默认开启。

### `LLM_EXAMPLE_SIMILAR_COUNT`

相似例子搜索个数限制，在 Workflow 模式下的例子选择步骤有效，默认值是 2。

### `LLM_RELATIVE_FUNCTIONS_COUNT`

相关函数搜索个数限制，在 Workflow 模式下的函数选择步骤有效，默认值是 3。

### `LLM_SUMMARY_MAX_DATA_BYTES`

模型对结果进行总结时，发送的数据部分最大字节数，默认值是 5000 字节。在 Workflow 模式下的总结步骤有效。

### `LLM_ENABLE_SUMMARY`

是否开启总结，在 Workflow 模式下的总结步骤有效，默认值是 true。如果只需要数据和图表，不需要总结，可以关闭以节省时间和费用。

### `LLM_RAW_DATA_MAX_VALUE_SIZE`

数据集原始字段值超过多少字节就不给这个值给大模型了，默认值是 30 字节。文本维度、日期等字段内容一般不会太长。太长的字段内容给大模型意义不大，比如 HTML 等。

### `ENABLE_QUESTION_REFINE`

是否开启用户问题优化功能，开启后会对用户问题进行优化再发送给大模型，默认开启。Workflow 模式下有效。如果问题保证比较具体，可以关闭以节省时间和费用。

### `USE_LLM_TO_SELECT_EXAMPLES`

是否用大模型选例子，默认是 true。在 Workflow 模式下有效。大模型选择例子相关性会相对高一些。

### `USE_LLM_TO_SELECT_DATASETS`

是否用大模型来精选数据集，默认是 false。关闭时，主要通过向量和分词算法来选择数据集。开启后，通过大模型对向量和分词的结果进行二次筛选，得到最相关的数据集。当选择结果不理想时，可以考虑开启，并在数据集知识管理中定义被选中的规则。

### `LLM_SELECT_DATASETS_NUM`

大模型从多少个最相关数据集中精选数据集，默认是 3。控制向量和分词初步筛选的分数最高的数据集个数。`USE_LLM_TO_SELECT_DATASETS` 开启时此配置才有意义。

### `SPLIT_FIELDS_BY_DATASET_IN_HQL_GENERATOR`

在 HQLGenerator 中是否分数据集列出字段和指标列表，默认关闭。Workflow 模式下有效。开启后可以提升多数据集组成的数据模型场景下字段和指标选择的准确性，但会增加提示词长度。

### `MEASURE_TOKENIZE_BATCH_SIZE`

业务指标分词分批处理大小，一般不用改，默认是 1000。

### `USE_FALLBACK_CHART`

是否开启保底 chart，用向量查询结果自动生成图表。默认是 false。默认生成的图表准确性不高，仅作为保底方案。

### `MAX_ITERATIONS`

在页面配置中是 `模型推理迭代上限`。最大迭代次数，用于控制处理大模型失败循环的次数，默认值是 3。

### `LLM_ENABLE_DRIVER`

是否开启驱动模式，默认关闭。内部测试用配置。

### 关键词配置

#### `CHAT_DATE_FIELD_KEYWORDS`

当有哪些关键字时，如果字段选择步骤没有选日期类型的字段，自动加上日期类型的字段。默认值是 "年,月,日,周,季,日期,时间,YTD,year,month,day,week,quarter,Q,date,time,变化,走势,趋势,trend"。

#### `CHAT_DATE_TREND_KEYWORDS`

当有哪些关键字时，判断为趋势计算。默认值是 "变化,走势,趋势,trend"。

#### `CHAT_DATE_COMPARE_KEYWORDS`

当有哪些关键字时，判断为同环比计算。默认值是 "同比,环比,增长,增量,减少,减量,异常,同期,相比,相对,波动,growth,decline,abnormal,fluctuation"。

#### `CHAT_RATIO_KEYWORDS`

当有哪些关键字时，判断为占比类计算。默认值是 "百分比,比例,比率,占比,percentage,proportion,ratio,fraction,rate"。

#### `CHAT_FILTER_TOKENS`

分词过滤掉哪些无意义的字词。默认值是 "的,于,了,为,年,月,日,时,分,秒,季,周,，,？,；,！,在,各,是,多少,（,）"。

### 安全配置

#### `CHAT_ENABLE_PROHIBITED_QUESTION`

是否开启禁用问题功能，开启后可以在控制台的 UserSystem Prompt 中配置禁止回答的问题规则。默认是 false。

#### `INPUT_GUARDRAILS`

输入安全护栏配置，用于过滤或限制用户输入。

#### `ENABLE_USER_ATTRIBUTE_PROMPT`

是否开启用户属性 prompt，开启后会根据用户填的用户属性带入相关信息给大模型。默认开启。

### 超时配置

#### `CHAT_SYNC_TIMEOUT`

API 调用时，同步等待问答结果默认最大等待时间，单位是毫秒，默认 60000 毫秒。API 请求也可以在 URL 参数中设置 timeout 以覆盖这个值。

***

## 五、Agent 功能配置

Agent 模式特有的配置项。

### `PREFER_AGENT_MODE`

设定是否默认使用 Agent 模式，默认是 Agent 模式。关闭后默认为 Workflow 模式。

### `ENABLE_STREAM`

是否开启大模型流式返回，默认开启

### `MAX_TURNS`

大模型对话最大轮次，默认值是 50。

### `BROWSER_USE_NO_PROGRESS_THRESHOLD`

Agent 连续调用 `browser_use` 工具但页面状态没有变化时，允许继续观察的最大轮数，默认值是 10。成功的点击、输入、导航等交互，或页面状态发生变化后，会重新开始计数。

该配置用于在页面探索没有进展时主动结束本轮 Agent 运行，避免持续占用浏览器资源。它不替代 `MAX_TURNS`：`MAX_TURNS` 控制 Agent 总轮次，`BROWSER_USE_NO_PROGRESS_THRESHOLD` 只控制连续无进展的浏览器工具轮次。

### `MAX_INPUT_TOKENS`

Agent 模式下大模型汇总记忆的最大 token 阈值，默认值是 25600

### `SCRATCH_PAD_TRIGGER`

设定关键字强制 Agent 使用草稿纸工具，关键字以英文逗号分割。

### `DISALLOW_SEARCH_GLOBAL_RESOURCES_WHEN_SPECIFIC_SOURCES`

设定指定数据源时禁止 Agent 搜索全局资源。

### `REVERSE_DATA_PROMPT_ORDER`

是否反转'数据'与'提示词'顺序，默认关闭。调试用配置。

### `NODE_AGENT_ENABLE`

是否开启衡石 AI Node Agent API 功能，以支持 API 调用方式也能用到 AI Agent。默认关闭。开启该功能需要额外的依赖要求和设置。

### `NODE_AGENT_TIMEOUT`

衡石 AI Node Agent 执行超时时间，单位毫秒，默认 600000 毫秒（10 分钟）。

### `NODE_AGENT_CLIENT_ID`

衡石 AI Node Agent 执行用到的衡石平台 API clientId，需要系统管理员生成并配置，需要支持 sudo。

### `DSL_EXAMPLE_NAMES`

查询 DSL 示例名称列表（逗号分隔），用于 Agent 学习 HQL 查询示例。默认值为 `HQLExamples,HQLCoreExamples`。可按需增删或替换为自定义示例名称，以调整 Agent 的查询模式学习范围。

### `SELF_EVOLUTION_ENABLED`

是否开启 Agent 自我进化功能（错误学习、对话洞察、用户偏好提取），默认关闭。设为 `true` 后开启自动学习；设为 `false` 时关闭。已保存的显式配置保持不变，升级后如需关闭此前开启的自动学习，请将此项设为 `false`。此开关不关闭正常问数和对话摘要。