{"record":{"id":"a29693adf7327397","repo":"jeecgboot/JeecgBoot","slug":"error-a29693","errorCode":null,"errorMessage":"向量存储失败：","messagePattern":"向量存储失败：","errorType":"exception","errorClass":"JeecgBootException","httpStatus":null,"severity":"error","filePath":"jeecg-boot/jeecg-boot-module/jeecg-boot-module-airag/src/main/java/org/jeecg/modules/airag/llm/handler/EmbeddingHandler.java","lineNumber":245,"sourceCode":"                // ignore：token获取不到默认为admin\n                username = \"admin\";\n            }\n        }\n        if (oConvertUtils.isNotEmpty(username)) {\n            metadata.put(EMBED_STORE_METADATA_USER_NAME, username);\n        }\n        //update-end---author:wangshuai---date:2025-12-26---for:【QQYUN-14265】【AI】支持记忆---\n        Document from = Document.from(content, metadata);\n        //update-begin---author:wangshuai ---date:2026-04-20  for：【issues/9551】HTML表格分段时被截断，保留完整表格块-----------\n        boolean hasHtmlTable = content != null && PATTERN_HTML_TABLE.matcher(content).find();\n        if (hasHtmlTable) {\n            try {\n                List<TextSegment> segments = splitDocumentPreservingHtmlTables(from, splitter);\n                List<Embedding> embeddings = embeddingModel.embedAll(segments).content();\n                embeddingStore.addAll(embeddings, segments);\n            } catch (Exception e) {\n                log.error(\"向量存储失败，请检查向量模型配置是否正确\", e);\n                throw new JeecgBootException(\"向量存储失败：\" + e.getMessage());\n            }\n        } else {\n            //update-begin---author:jeecg---date:2026-02-26---for:[#9374]【AI知识库】千帆向量报错，添加异常处理防止空指针\n            try {\n                ingestor.ingest(from);\n            } catch (Exception e) {\n                log.error(\"向量存储失败，请检查向量模型配置是否正确\", e);\n                throw new JeecgBootException(\"向量存储失败：\" + e.getMessage());\n            }\n            //update-end---author:jeecg---date:2026-02-26---for:[#9374]【AI知识库】千帆向量报错，添加异常处理防止空指针\n        }\n        //update-end---author:wangshuai ---date:2026-04-20  for：【issues/9551】HTML表格分段时被截断，保留完整表格块-----------\n\n        return metadata.toMap();\n    }\n\n    /**\n     * 创建分段器","sourceCodeStart":227,"sourceCodeEnd":263,"githubUrl":"https://github.com/jeecgboot/JeecgBoot/blob/96fb33f5ec68516da0b0147da06b2eb0419e063a/jeecg-boot/jeecg-boot-module/jeecg-boot-module-airag/src/main/java/org/jeecg/modules/airag/llm/handler/EmbeddingHandler.java#L227-L263","documentation":"Thrown by EmbeddingHandler during vector storage when the document content contains HTML tables. The code splits the document preserving HTML table blocks, generates embeddings via embeddingModel.embedAll(segments), and stores them via embeddingStore.addAll(). Any exception in this pipeline is caught and re-thrown as JeecgBootException with the original message appended.","triggerScenarios":"A knowledge-base document whose parsed content matches PATTERN_HTML_TABLE triggers the special table-preserving split path. The failure occurs in embedAll() (embedding model API error, timeout, rate limit) or addAll() (vector store connectivity issue, dimension mismatch, authentication failure).","commonSituations":"Embedding model API key is invalid or expired; vector database (pgvector/Milvus) is unreachable or the embedding dimensions do not match the vector store schema; rate limiting from the embedding provider; the embedding model returns an error for very large table segments.","solutions":["Check the vector model configuration (API key, endpoint, model name) in the AI knowledge-base settings.","Verify the vector database is running and the collection/table schema matches the embedding dimension of the configured model.","Check application logs for the original exception (logged at ERROR level with '向量存储失败，请检查向量模型配置是否正确') to identify whether the failure is in embedding generation or vector storage.","If the table is very large, consider reducing chunk size in the splitting strategy."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Before embedding, verify model config\nif (embeddingModel == null) {\n    throw new JeecgBootException(\"向量模型未配置\");\n}\nif (embeddingStore == null) {\n    throw new JeecgBootException(\"向量存储未配置\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    // embedding logic for HTML table content\n} catch (JeecgBootException e) {\n    if (e.getMessage().startsWith(\"向量存储失败\")) {\n        log.error(\"Vector storage failed, check model config: {}\", e.getMessage());\n        // notify user to check vector model configuration\n    }\n    throw e;\n}","preventionTips":["Validate embedding model configuration (API key, endpoint) before processing documents.","Test the embedding model with a small document before batch processing.","Monitor vector store connectivity and disk space proactively.","For documents with large HTML tables, consider pre-splitting to reduce segment size."],"tags":["vector-store","embedding","rag","configuration"],"backgroundTag":null,"analyzedSha":"96fb33f5ec68516da0b0147da06b2eb0419e063a","analyzedAt":"2026-08-14T00:04:16.786Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}