知识库文件解析失败：一次由 Domain Index 引发的定位记录

知识库上传文件后，解析流程不一定失败在文件本身。有时日志只暴露出“保存分块失败”，真正的问题却在数据库对象状态上。笔者环境中，这次问题最终定位到 Oracle 表上的 Domain Index 处于 failed 状态。

01 | 先用小文件复现问题

为了快速验证，笔者先用一个小文件复现。上传后，解析任务能被 Worker 接收，但写入分块时报错：

2026-07-12 07:34:31: Worker received task, preparing to parse
2026-07-12 07:36:33: Error saving chunks to database: Oracle batch insert text chunks failed

这个日志说明：文件解析流程已经进入后台任务，但在保存 chunks 到数据库时失败。因此排查重点可以先放在目标表、索引和批量写入相关对象上。

02 | 检查目标表上的 Domain Index

问题最终定位为：AI_PLATFORM.KBOT_BIZ_TXT_EMBEDDING 表上存在 failed 的 Domain Index。

用于检查 Domain Index 状态的 SQL 如下：

SELECT i.owner,
 i.index_name,
 c.column_name,
 i.index_type,
 i.status,
 i.domidx_status,
 i.domidx_opstatus
 FROM dba_indexes i
 LEFT JOIN dba_ind_columns c
 ON c.index_owner = i.owner
 AND c.index_name = i.index_name
 WHERE i.table_owner = 'AI_PLATFORM'
 AND i.table_name = 'KBOT_BIZ_TXT_EMBEDDING'
 AND i.index_type = 'DOMAIN'
 ORDER BY i.index_name, c.column_position;

为了保留现场，也可以先导出相关索引创建语句：

SET LONG 1000000
SET LONGCHUNKSIZE 1000000
SET PAGESIZE 0
SET LINESIZE 32767
SET TRIMSPOOL ON

SPOOL /tmp/kbot_text_indexes.sql

SELECT DBMS_METADATA.GET_DDL('INDEX', 'IDX_FULLSEARCH_TXT_HEADER', 'AI_PLATFORM')
FROM dual;

SELECT DBMS_METADATA.GET_DDL('INDEX', 'IDX_FULLSEARCH_TXT_EMBEDDING', 'AI_PLATFORM')
FROM dual;

SPOOL OFF

其中一个索引创建语句如下：

CREATE INDEX "AI_PLATFORM"."IDX_FULLSEARCH_TXT_EMBEDDING"
ON "AI_PLATFORM"."KBOT_BIZ_TXT_EMBEDDING" ("CONTENT")
INDEXTYPE IS "CTXSYS"."CONTEXT"
PARAMETERS ('lexer chinese_lexer')

本次处理时，先删除处于 failed 状态的异常索引：

DROP INDEX AI_PLATFORM.IDX_FULLSEARCH_TXT_EMBEDDING FORCE;

03 | 修复后重新验证

处理完相关索引后，再次检查状态，Domain Index 已恢复正常：

OWNER INDEX_NAME COLUMN_NAME INDEX_TYPE STATUS DOMIDX_STATUS DOMIDX_OPSTATUS
AI_PLATFORM IDX_FULLSEARCH_TXT_EMBEDDING CONTENT DOMAIN VALID VALID VALID

OWNER INDEX_NAME COLUMN_NAME INDEX_TYPE STATUS DOMIDX_STATUS DOMIDX_OPSTATUS
AI_PLATFORM IDX_FULLSEARCH_TXT_HEADER HEADER DOMAIN VALID VALID VALID

OWNER INDEX_NAME COLUMN_NAME INDEX_TYPE STATUS DOMIDX_STATUS DOMIDX_OPSTATUS
AI_PLATFORM IDX_FULLSEARCH_TXT_SEARCH_HELPER SEARCH_HELPER DOMAIN VALID VALID VALID

随后上传同一个文件，解析成功：

2026-07-12 08:15:31: Worker received task, preparing to parse
2026-07-12 08:17:47: Successfully saved 1 chunks with embeddings

这次排查的关键点是：当知识库文件解析报出 Oracle batch insert text chunks failed 时，不要只看文件内容或解析程序，也要检查写入表上的 Domain Index 状态。

关注我，和AI一起成长~