分类：HZERO问题运维

一、背景

HZERO 低代码平台提供了「AI 助手」功能，用户通过上传界面截图或描述需求，AI 自动生成业务对象和页面。该功能由 AIP（AI 平台）的 Agent 编排实现，涉及 hzero-aip-app、hzero-aip-server、hzero-modeler 等多个微服务协同。

测试过程中连续遇到两个错误，本文记录了作为 AI Agent 如何逐步分析、定位并解决问题的完整过程。

二、问题一：domainCode 缺失

2.1 现象

在 AIP 中台直接调用「AIGC 生成低代码业务对象和页面」Agent 编排，执行到「批量创建对象」节点时报错：

CommonException: 程序出现错误，请联系管理员

2.2 分析过程

第一步：看截图，定位错误节点

用户提供了错误截图，显示错误发生在流程的「批量创建对象」节点，异常类型为 CommonException，调用栈指向 AbstractInnerRequestNodeHandler.execute。

判断方向：这是 Agent 流程中的内部接口调用节点，调用了低代码平台的后端接口，接口返回了错误。

第二步：查容器状态，确认服务存活

docker ps --format '{{.Names}}\t{{.Status}}' | grep -i aip

结果：hzero-aip-server 和 hzero-aip-app 都 Up 7 hours，排除服务宕机。

第三步：拉日志，精确定位错误

先看 hzero-aip-app（Agent 流程执行方）的日志，过滤错误关键词：

docker logs hzero-aip-app --since 30m 2>&1 | grep -i "error\|exception\|批量创建\|InnerRequest" | tail -50

找到关键错误：

ERROR --- Failed on node AIGC 生成低代码业务对象和页面/LOWCODE.BUSINESS_OBJECT_PAGE/INTERNAL_INTERFACE_...
io.choerodon.core.exception.CommonException: 程序出现错误，请联系管理员
  at ResponseUtils.getResponse(ResponseUtils.java:133)
  at AbstractInnerRequestNodeHandler.execute(AbstractInnerRequestNodeHandler.java:199)

这说明 aip-app 调用了某个内部接口，接口返回了非成功响应，ResponseUtils 解析后抛出通用异常。

第四步：查被调用方日志，找到真实错误

错误堆栈显示调用链终止在 aip-app，但真正的错误来自被调用的服务。查看 hzero-modeler 日志：

docker logs hzero-modeler --since 30m 2>&1 | grep -i "error\|exception\|simple-generator" | tail -30

找到根因：

MissingServletRequestParameterException: Required request parameter 'domainCode' for method parameter type String is not present
  Request: {URI=/v1/0/business-objects/domain/simple-generator}

第五步：回溯参数，确认 domainCode 为 null

回到 aip-app 日志，查看脚本节点的参数输出：

脚本节点参数:{businessObjectList=[...], domainCode=null, pageList=[...]}

确认：domainCode 为 null，导致低代码平台接口报 400 错误。

2.3 根因

Agent 编排流程中，domainCode 需要从低代码平台的上下文中获取。用户直接在 AIP 中台调用 Agent 编排，没有进入低代码平台的领域上下文，导致 domainCode 为空。

2.4 解决方案

从低代码平台进入领域后调用 AI 助手。在低代码平台的工作台中先进入一个领域（如”调研问卷”），再点击 AI 助手按钮，这样 domainCode 会作为上下文参数自动传入 Agent 流程。

2.5 验证

用户从低代码平台领域内调用 AI 助手后，domainCode 正确传入（值为 RSHQ），第一个问题解决。

三、问题二：业务对象依赖顺序错误

3.1 现象

domainCode 问题解决后，AI 成功生成了业务对象和页面数据，但在「批量创建对象」节点再次报错：

CommonException: 业务对象[RS_MEMBERSHIP_CARD]不存在

3.2 分析过程

第一步：看截图，识别新错误

从截图看到错误信息变为「业务对象[RS_MEMBERSHIP_CARD]不存在」，不再是通用的”程序出现错误”，而是一个具体的业务校验错误。

判断方向：这次不是参数缺失，而是业务逻辑问题——接口在创建某个对象时，发现它依赖的另一个对象不存在。

第二步：查日志，确认调用链

docker logs hzero-aip-app --since 15m 2>&1 | grep -i "error\|RS_MEMBERSHIP\|不存在" | tail -30

找到：

ERROR --- Failed on node ...INTERNAL_INTERFACE_...
CommonException: 业务对象[RS_MEMBERSHIP_CARD]不存在

hzero-modeler 侧也确认：

Common exception, Request: {URI=/v1/0/business-objects/domain/simple-generator}
CommonException: 业务对象[RS_MEMBERSHIP_CARD]不存在

第三步：分析数据，发现依赖关系

从 aip-app 日志中提取 AI 生成的业务对象数据：

• RS_MEMBER（会员信息）：包含一个 MASTER_RELATION 类型字段 membershipCard，指向 RS_MEMBERSHIP_CARD
• RS_MEMBERSHIP_CARD（会员卡信息）：被 RS_MEMBER 引用

两个对象都是 CREATE 模式（新建），businessObjectList 中 RS_MEMBER 排在前面。

问题就在这里：批量创建时，RS_MEMBER 先被处理，它的 MASTER_RELATION 字段引用了还不存在的 RS_MEMBERSHIP_CARD，低代码平台校验依赖对象是否存在时失败。

第四步：审查脚本节点代码

用户提供了「页面&业务对象参数处理」脚本节点的完整代码。审查后发现两个问题：

1. 没有依赖排序：businessObjectList 按原始顺序传给 API，没有按 MASTER_RELATION 依赖关系排序
2. masterBusinessObjectCode 未同步更新：脚本给 businessObjectCode 加了 domainCode 前缀（如 RSHQ_RS_MEMBER），但字段里的 masterBusinessObjectCode 没同步更新，仍指向旧编码 RS_MEMBERSHIP_CARD

3.3 根因

脚本节点缺少两个关键处理：

1. 业务对象未按依赖关系排序，导致被引用对象排在引用者之后
2. 加 domainCode 前缀后，MASTER_RELATION 字段的 masterBusinessObjectCode 指向了不存在的旧编码

3.4 解决方案

在脚本节点中增加两处修复：

修复 1：同步更新 masterBusinessObjectCode

在遍历 businessObjectFields 的循环中增加：

if(field.componentType === 'MASTER_RELATION' && field.masterBusinessObjectCode
   && boCodeToNewMap.has(field.masterBusinessObjectCode)) {
  field.masterBusinessObjectCode = boCodeToNewMap.get(field.masterBusinessObjectCode);
}

修复 2：拓扑排序

在 return 之前，对 businessObjectList 做 Kahn 拓扑排序：

function sortByDependency(objList){
  if(!objList || objList.length <= 1) return objList;

  var codeSet = {};
  objList.forEach(function(o){ codeSet[o.businessObjectCode] = true; });

  var deps = {};
  var inDegree = {};
  objList.forEach(function(o){
    deps[o.businessObjectCode] = [];
    inDegree[o.businessObjectCode] = 0;
  });

  objList.forEach(function(o){
    if(o.businessObjectFields){
      o.businessObjectFields.forEach(function(f){
        if(f.componentType === 'MASTER_RELATION' && f.masterBusinessObjectCode
           && codeSet[f.masterBusinessObjectCode]){
          deps[f.masterBusinessObjectCode].push(o.businessObjectCode);
          inDegree[o.businessObjectCode]++;
        }
      });
    }
  });

  var queue = [];
  objList.forEach(function(o){
    if(inDegree[o.businessObjectCode] === 0) queue.push(o.businessObjectCode);
  });

  var sorted = [];
  while(queue.length > 0){
    var code = queue.shift();
    var obj = objList.find(function(o){ return o.businessObjectCode === code; });
    if(obj) sorted.push(obj);
    deps[code].forEach(function(dep){
      inDegree[dep]--;
      if(inDegree[dep] === 0) queue.push(dep);
    });
  }

  // 循环依赖兜底
  if(sorted.length < objList.length){
    objList.forEach(function(o){
      var found = false;
      for(var i = 0; i < sorted.length; i++){
        if(sorted[i].businessObjectCode === o.businessObjectCode){ found = true; break; }
      }
      if(!found) sorted.push(o);
    });
  }

  return sorted;
}

3.5 验证

用户更新脚本节点后重新测试，业务对象和页面成功创建。

四、方法论总结：AI Agent 如何排查问题

4.1 排查框架

整个排查过程遵循一个清晰的框架：

截图/现象 → 服务状态 → 日志分析 → 参数回溯 → 代码审查 → 定位根因 → 修复验证

4.2 关键原则

原则	说明	实际应用
先看现象，不急于下结论	错误截图是最直接的信息源	第一次看到 CommonException 通用错误，不能止步于此，需要追查具体原因
服务存活先确认	排除基础设施问题	docker ps 确认容器都在运行
调用方与被调用方日志对照看	错误往往在被调用方	aip-app 抛通用异常，hzero-modeler 才有具体错误
参数回溯定位数据问题	日志中的参数数据是关键证据	从脚本节点日志中找到 domainCode=null 和 businessObjectList 的完整数据
代码审查发现逻辑缺陷	静态分析补充动态调试	审查脚本代码发现缺少排序和字段同步
一次只改一个问题	控制变量，便于验证	先修 domainCode，再修依赖顺序

4.3 工具使用策略

阶段	工具/命令	目的
服务检查	docker ps	确认容器存活状态
日志检索	docker logs --since + grep	精确过滤错误信息
参数分析	日志中的脚本节点参数输出	回溯传入接口的实际数据
代码审查	人工提供脚本源码	静态分析逻辑缺陷
修复验证	用户在平台上重新执行	端到端验证

4.4 AI Agent 的优势

在这次排查中，AI Agent 展现了几个独特优势：

1. 多服务日志关联分析：同时查看 aip-app、aip-server、modeler 三个服务的日志，快速关联调用链，人工排查往往需要切换多个终端窗口
2. 从海量日志中精准提取关键信息：在数万行日志中用 grep 精确定位到 3 行关键错误，避免了人工翻阅的眼疲劳
3. 数据与代码交叉验证：从日志中提取业务对象数据结构，再对照脚本代码分析，快速发现两个缺陷
4. 直接给出可执行的修复代码：拓扑排序算法、字段同步逻辑，不需要人工再翻译成代码

五、涉及的容器服务

服务	角色
hzero-aip-app	AI 应用前端，执行 Agent 流程编排
hzero-aip-server	AI 平台后端，处理 LLM 调用、知识检索
hzero-modeler	低代码建模服务，提供业务对象/页面创建 API
hzero-lowcode	低代码前端服务
hzero-lowcodedata	低代码数据服务

六、结论

两个问题的根因不同但都出在「参数传递」环节：

1. 问题一是上下文参数（domainCode）未传入 — 需要从正确的入口调用
2. 问题二是脚本节点对参数的处理不完整 — 缺少依赖排序和字段同步

修复后，AI 助手能够正确生成业务对象和页面，整个链路跑通。建议将脚本修复同步到产品主线版本。

问题背景

客户需求：在 HZERO 后端根据用户账号获取对应的 Token。客户原思路是”根据账号查出密码 → 解密 → 调用登录接口获取 Token”。

一、为什么”查密码→解密”方案不可行

HZERO 用户密码使用 BCrypt 单向哈希算法存储，数据库中保存的是哈希值，不可逆、不可解密。因此”从数据库查出密码 → 解密 → 调用登录接口”这条路在技术上走不通。

二、根据是否有用户明文密码，分两种方案

方案一：有用户明文密码 — 标准 OAuth2 password 模式

如果调用方持有用户的明文密码（例如用户自己输入），HZERO 原生支持标准 OAuth2 Password Grant，直接调用即可获取 Token，无需二次开发：

请求：

POST /oauth/oauth/token
Authorization: Basic <Base64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=用户账号&password=明文密码

返回示例：

{
  "access_token": "***",
  "token_type": "bearer",
  "refresh_token": "***",
  "expires_in": 32399999,
  "scope": "default"
}

注意事项：

• 端点路径是 /oauth/oauth/token（两层 oauth 路径，不是 /oauth/token）
• client_id 和 client_secret 使用项目实际配置的客户端凭据
• 密码传输明文，建议接口走 HTTPS
• Token 有效期可通过 OAuth 服务端配置调整

方案二：无用户明文密码 — 自定义登录接口（二开）

如果调用方没有用户密码（例如服务间调用、管理端代操作等场景），需要在 hzero-oauth 服务中进行二次开发，实现自定义认证流程。

HZERO 已提供了标准扩展组件 LoginTokenService，核心开发步骤如下：

1. 自定义认证对象 AuthenticationToken

继承 AbstractAuthenticationToken，封装认证信息（如用户账号 + 加签字符串）：

public class CustomAuthenticationToken extends AbstractAuthenticationToken {

    private final Serializable principal;  // 用户账号
    private final String sign;             // 加签字符串

    // 未认证构造方法
    public CustomAuthenticationToken(Serializable principal, String sign) {
        super(null);
        this.principal = principal;
        this.sign = sign;
        setAuthenticated(false);
    }

    // 已认证构造方法
    public CustomAuthenticationToken(Serializable principal,
            Collection<? extends GrantedAuthority> authorities) {
        super(authorities);
        this.principal = principal;
        this.sign = null;
        super.setAuthenticated(true);
    }

    @Override
    public Serializable getCredentials() { return null; }

    @Override
    public Serializable getPrincipal() { return this.principal; }

    public String getSign() { return this.sign; }
}

2. 自定义认证器 AuthenticationProvider

实现 AuthenticationProvider 接口，在 authenticate() 方法中：

• 校验加签字符串（自定义安全逻辑）
• 通过 UserDetailsService 加载用户
• 返回已认证的 Authentication

@Component
public class CustomAuthenticationProvider implements AuthenticationProvider {

    @Autowired
    private UserDetailsService userDetailsService;

    @Override
    public Authentication authenticate(Authentication authentication) {
        CustomAuthenticationToken token = (CustomAuthenticationToken) authentication;
        String username = (String) token.getPrincipal();
        String sign = token.getSign();

        // 1. 校验加签字符串（自定义安全逻辑）
        // TODO: 实现你的签名校验逻辑，例如 HMAC/RSA 验签

        // 2. 加载用户
        UserDetails user = userDetailsService.loadUserByUsername(username);

        // 3. 返回已认证的 Authentication
        return new CustomAuthenticationToken(username, user.getAuthorities());
    }

    @Override
    public boolean supports(Class<?> authentication) {
        return CustomAuthenticationToken.class.isAssignableFrom(authentication);
    }
}

3. 自定义 LoginTokenService

继承 LoginTokenService，在 attemptAuthentication() 中从请求提取参数：

public class CustomLoginTokenService extends LoginTokenService {

    public CustomLoginTokenService(TokenGranter tokenGranter,
            ClientDetailsService clientDetailsService,
            OAuth2RequestFactory oAuth2RequestFactory,
            CustomAuthenticationProvider authenticationProvider) {
        super(tokenGranter, clientDetailsService, oAuth2RequestFactory, authenticationProvider);
    }

    @Override
    protected Authentication attemptAuthentication(HttpServletRequest request) {
        String username = request.getParameter("username");
        String sign = request.getParameter("sign");
        return new CustomAuthenticationToken(username, sign);
    }
}

4. 配置类

@Configuration
@AutoConfigureAfter(AuthorizationServerEndpointsConfiguration.class)
public class TokenConfiguration {

    private final AuthorizationServerEndpointsConfigurer endpoints = new AuthorizationServerEndpointsConfigurer();

    @Autowired
    private List<AuthorizationServerConfigurer> configurers = Collections.emptyList();

    @PostConstruct
    public void init() {
        for (AuthorizationServerConfigurer configurer : configurers) {
            try {
                configurer.configure(endpoints);
            } catch (Exception e) {
                throw new IllegalStateException("Cannot configure endpoints", e);
            }
        }
    }

    @Bean
    public CustomLoginTokenService customLoginTokenService(
            CustomAuthenticationProvider customAuthenticationProvider) {
        return new CustomLoginTokenService(
            endpoints.getTokenGranter(),
            endpoints.getClientDetailsService(),
            endpoints.getOAuth2RequestFactory(),
            customAuthenticationProvider
        );
    }
}

5. 登录接口

@RestController
public class CustomLoginController {

    @Autowired
    private CustomLoginTokenService customLoginTokenService;

    @PostMapping("/token/custom")
    public ResponseEntity<AuthenticationResult> loginToken(HttpServletRequest request) {
        AuthenticationResult result = customLoginTokenService.loginForToken(request);
        return Results.success(result);
    }
}

调用方式：

POST /oauth/token/custom
Content-Type: application/x-www-form-urlencoded

username=用户账号&sign=加签字符串&client_id=xxx&client_secret=***

三、详细文档参考

开放平台文档《定制登录获取令牌》：

https://open.hand-china.com/document-center/doc/product/10002/11014

文档中包含完整的类图说明和短信验证码登录的代码示例，可直接参考。另外文档目录中还有《非标单点登录示例》也可作为补充参考。

更新向量模型之后如何成功重建索引

作者：H0总助  |  文档版本：V1.0  |  适用平台：HZERO AIGC平台 1.6.1

一、引言

在HZERO AIGC平台的使用过程中，有时需要更换底层向量模型。例如原来使用的是豆包的向量模型 doubao-embedding-large-text-250515，现在要切换到阿里的 text-embedding-v4。切换完成后，文档库中已有的文档需要重建向量索引，才能让知识问答功能继续正常工作。

本文档详细记录了从切换向量模型到成功重建索引的完整操作步骤，包括过程中可能遇到的两个典型报错及其解决方法，供益吉的海森以及其他遇到类似问题的同学参考。

二、背景：为什么要换向量模型

原先系统中使用的豆包向量模型 doubao-embedding-large-text-250515 已无法使用（豆包已不再提供纯文本向量模型服务），因此需要切换到阿里的文本向量模型 text-embedding-v4。

切换流程大致如下：

在模型对接配置中新建阿里 text-embedding-v4 对接账户

在模型组合配置中创建新的向量组合（如”Jack文本向量组合-阿里”），关联阿里向量模型

在全局选项配置中，将默认文本向量模型改为新建的组合

删除旧的向量索引，然后重建

三、第一步：准备新的向量模型对接

这是最基础的一步，但有一个容易忽略的细节：向量维度。

3.1 确认向量模型的维度

不同的向量模型输出的向量维度是不同的：

向量模型	输出维度	说明
doubao-embedding-large-text-250515	2048	豆包旧版纯文本向量模型，已停止服务
text-embedding-v4（阿里）	1024	阿里当前最新文本向量模型
doubao-embedding-vision（豆包）	多种可选	豆包新版图文向量模型

如果你的旧索引是用 2048 维度建的，现在换成了 1024 维度的模型，那重建索引时就会报错（见第五节）。

3.2 在值集中添加新维度（如果需要的话）

新建模型对接账户时，当你选择了”向量-阿里”这个模型类型后，系统要求你选择一个维度值。如果下拉菜单中找不到 1024 这个选项，说明值集中没有这个维度的配置。

操作路径：

系统管理 > 值集管理 > 搜索”向量模型维度”（或类似名称） > 在值集值列表中添加一条新记录，值填写 1024，含义填写”阿里向量模型维度”或其他便于识别的名称。

添加完成后回到模型对接配置页面，刷新后 1024 就会出现在下拉选项中了。

3.3 新建模型对接账户

在”模型对接配置”页面，点击”新建”按钮，填写以下信息：

字段	填写内容	说明
账户编码	JACK-TEXT-EMBEDDING-ALI	自定义，建议有意义的命名
模型分类	向量-阿里	选择阿里文本向量模型分类
模型类型	text-embedding-v4	选择对应的阿里模型
维度	1024	选择刚添加到值集中的维度
ak/sk等凭证	根据实际情况填写	阿里云的API访问凭证

配置完成后点击”测试”按钮，确认返回正确的向量值，表示对接成功。

3.4 创建新的模型组合

在”模型组合配置”页面，点击”新建”：

– 组合名称：例如 “Jack文本向量组合-阿里”

– 模型角色：文本向量

– 策略选择：轮询（如果有多个模型需要均衡）或优先级

– 关联模型：选择刚才新建的阿里向量模型对接账户

创建完成后点击”测试”，验证组合可用。

3.5 设置为默认文本向量模型

在”全局选项配置”页面，找到”默认文本向量模型”配置项：

点击编辑，将原来的默认向量组合改为刚创建的”Jack文本向量组合-阿里”

保存并确认弹窗

四、第二步：清理旧索引并重建

换了向量模型后，旧的索引映射（mapping）依然保持着旧模型的维度设定（如2048），与新模型（1024）不匹配。因此需要清理旧索引，让系统重新创建。

4.1 查看并释放旧索引

在”向量库集合管理”页面，可以看到所有已有的索引，通常包括：

haip_doc_chunks_0 文档索引

haip_question_index_0 问题索引

haip_dictionary_value_0 词典索引

haip_feature_word_0 特征词索引

haip_summary_index_0 摘要索引

逐个点击操作列的”释放”按钮释放索引。释放后索引会出现在底部列表中，再点击”删除”彻底移除。注意：释放和删除是两步操作，缺一不可。

4.2 检查文档同步状态

清理索引后，导航到”文档库管理”页面，你会发现文档的”状态”列仍然显示”已同步到向量库”或”已同步到ES”。这是因为文档表中记录的状态缓存未被清理。重新同步时会自动更新状态，不影响后续操作。

4.3 执行同步

在文档库管理页面，可以选中一个或多个文档，点击”同步处理” > “选择同步” 进行单文档测试，或点击”全部同步”批量重建索引。系统会重新读取文档内容、切片、调用向量模型生成embedding并写入新的ES索引。

五、常见问题一：向量维度不匹配（Failed: X document(s) failed to index）

5.1 错误现象

在执行文档同步时，右下角弹出红色错误提示：

“资源同步失败 – 内容同步(向量库) – Failed: 10 document(s) failed to index.”

点开文档的同步信息详情，可以看到更具体的错误：

“The [dense_vector] field [embedding] in doc … has a different number of dimensions [1024] than defined in the mapping [2048].”

5.2 原因分析

ES向量索引的mapping中预定义的向量维度是2048（来自原来的豆包模型），但新模型阿里 text-embedding-v4 输出的向量维度是1024。写入时维度不一致，ES拒绝写入。

5.3 解决方法

按照第四节的步骤，在值集中添加1024维度 → 新建维度为1024的模型账户 → 新建组合 → 设为默认 → 删除旧索引 → 重建同步。新索引创建时会自动按新模型维度建立mapping。

⚠️ 关键注意点：向量维度一旦在模型对接账户中配置，后续不可修改。如果要换维度，只能新建一个模型对接账户，不能编辑原有的。

六、常见问题二：PDF图片识别失败（调用HKMS执行文件切片时发生错误）

6.1 错误现象

执行同步后，右下角弹出错误提示：

“调用HKMS执行文件切片时发生错误: I/O error on POST request for http://hzero-hkms:18080/kms/loader/v2/process_file: Timeout”

或：

“调用HKMS执行文件切片时发生错误: Failed: 67/19 document(s) failed to index.”

查看hzero-hkms容器日志，会发现大量WARNING级别的报错：

“response from Hzero API: {failed: True, code: haip.error.arrange.account_config.not_exists, message: ‘模型{0}不可用，请重新选择其他模型。’}”

6.2 原因分析

这个错误的根本原因不是向量模型的问题，而是PDF处理流程中的一个关键环节：

HKMS在执行文档切片（process_file）时，对于PDF文件中的图片，需要调用一个多模态大模型来解释图片内容（图片说明/OCR）。这个图片识别走的是”全局选项配置”中的”图片识别模型”配置，而不是”默认对话模型”。

如果你的”图片识别模型”组合中配置了已下架或不可用的模型（例如kimi-2.5已下架），图片识别就会失败，进而导致整个文档切片处理异常并超时。

6.3 解决方法

步骤1：在”模型组合配置”中找到当前配置为”图片识别模型”的那个组合。

步骤2：检查该组合中包含的模型是否都可用（特别是有没有已经下架的模型）。

步骤3：如果某个模型已不可用，在组合中禁用它或切换到其他可用的模型（例如doubao-seed-1.8）。

步骤4：重新测试组合是否可用（点击测试按钮）。

步骤5：确认”默认对话模型”不需要修改，可以继续保持使用纯文本对话模型（如deepseek-V3），因为”图片识别模型”是独立配置的，两者互不干扰。

步骤6：重新执行文档同步（选择同步或全部同步）。

七、完整操作流程一览

以下是更换向量模型后、重建索引成功的完整操作流程，按顺序执行即可：

序号	步骤	操作位置	说明
1	确认新模型的向量维度	模型文档/阿里官网	例如阿里 text-embedding-v4 = 1024 维
2	值集中添加新维度（如需）	值集管理 > 向量模型维度	如果维度选项不存在，先添加
3	新建模型对接账户	模型对接配置	选择模型分类、类型、维度
4	新建模型组合	模型组合配置	关联刚建的模型账户
5	设为默认文本向量模型	全局选项配置	修改默认文本向量模型配置项
6	检查图片识别模型是否可用	模型组合配置	若有已下架模型，更换或禁用
7	释放并删除旧向量索引	向量库集合管理	逐条释放后再删除
8	执行文档同步	文档库管理	选”选择同步”测试或”全部同步”批量
9	验证知识问答功能	AI对话/知识问答	确认能正确检索文档内容

备注：向量模型更改后，原来的向量索引被全部删除，除了文档索引需要重建外，
Agent词典、Agent编排的唤醒词 也要向量同步，否则回导致智能导航和多Agent应用唤醒Agent不可用。

八、避坑指南与关键要点

8.1 关于向量维度

向量维度一旦在模型对接账户中配置，后续不可修改

如需更改维度，只能新建一个模型对接账户

新建账户时如果维度选不到，先去值集管理中添加

同一个向量模型可能有多个维度版本，务必确认正确的值

8.2 关于模型组合中的已下架模型

AI模型厂商经常下架旧版本模型，下架后虽然账户还在，但实际调用会失败

检查模型组合时，不仅要看是否有模型，还要看模型是否仍然可用

如果一个组合中有多个模型，其中一个不可用会导致整个组合失败吗？取决于策略配置。轮询策略下如果轮询到已下架模型就会失败，建议禁用或移除已下架的模型。

8.3 关于图片识别模型的独立配置

PDF中的图片识别走的是”图片识别模型”配置，不是”默认对话模型”

这意味着你可以在对话中使用纯文本模型（如DeepSeek-V3），同时使用多模态模型处理PDF图片

两者互不干扰，不需要为了文档同步而修改默认对话模型

8.4 排查思路总结

如果文档向量索引重建失败，建议按以下顺序排查：

第一步：查看hzero-hkms的容器日志，找到具体的错误信息

第二步：如果是”dimensions mismatch”相关错误，检查向量维度是否匹配

第三步：如果是”file切片超时”或”model not exists”相关错误，检查图片识别模型的配置

第四步：修复后重新执行同步测试

九、总结

更换向量模型后重建索引，本质上是处理两个层面的问题：一是”数据格式”层面——新模型输出的向量维度与旧索引mapping不一致；二是”模型调用”层面——图片识别依赖的模型是否可用。

两个问题都解决后，文档向量索引重建和知识问答功能就能正常工作。希望本文能帮助你在遇到类似问题时，更快地定位和解决问题。

—END—

附图：

在“服务 + 插件”架构中，平衡服务与插件的发展，需从规划、开发、管理与评估等多方面着手：
1. 前期规划
– **明确主次与边界**：清晰界定服务和插件的核心功能与职责。服务应提供稳定、基础的功能框架，像电商系统的用户管理、订单处理服务，保障系统基本运作；插件则侧重于拓展和个性化定制，如个性化推荐插件、营销活动插件。避免功能重叠，确保二者相辅相成。
– **制定协同发展路线图**：结合业务战略，规划服务与插件的长期发展路径。明确不同阶段服务升级与插件开发计划。例如，在新业务拓展初期，先完善基础服务，随后围绕新业务开发相关插件，实现二者有序推进。
2. 开发过程
– **遵循统一标准**：建立统一的技术标准和接口规范，确保服务与插件间无缝对接。如规定统一的数据格式、通信协议，无论服务还是插件开发，都依此标准，降低集成难度，提高兼容性与可维护性。
– **保障兼容性**：服务升级时，充分考虑现有插件兼容性，避免接口或数据结构变动致插件失效。同样，插件开发也应适配服务的当前与未来版本。可通过版本管理和兼容性测试机制，如语义化版本号，确保二者协同演进。
– **促进双向反馈**：开发服务与插件的团队保持紧密沟通。服务团队及时向插件团队通报服务架构、接口变化；插件团队反馈插件开发中遇的问题与需求，助服务团队优化设计，实现协同优化。
3. 管理与维护
– **资源合理分配**：依据业务需求与发展阶段，合理分配人力、物力资源。若某阶段重点拓展服务功能，适当增加服务开发资源；若需丰富插件生态，侧重插件开发投入，确保资源与发展重点匹配。
– **建立测试与监控体系**：构建全面测试机制，涵盖单元测试、集成测试、功能测试等，确保服务与插件功能正常及协同工作稳定。同时，搭建监控系统，实时监测性能指标，如响应时间、资源利用率，及时发现处理问题。
– **版本管理与发布协调**：规范服务与插件版本管理，确保版本对应清晰。发布新版本时，协调发布时间与内容，提前通知相关方，做好升级准备与过渡，降低对业务影响。
4. 评估与优化
– **收集用户反馈**：通过多种渠道收集用户对服务与插件的反馈，了解使用体验、需求与问题。如设置用户反馈渠道、开展用户调研，依据反馈优化服务与插件功能。
– **定期评估**：定期评估服务与插件发展情况，对比规划目标，分析进展与偏差。采用关键指标评估，如服务稳定性、插件使用率、用户满意度等，据此调整发展策略。
– **持续优化**：基于评估结果与用户反馈，持续优化服务与插件。对服务性能瓶颈优化，对插件功能改进拓展，使二者不断适应业务发展与用户需求。