@nocobase/plugin-ai 2.1.6 → 2.1.8

package/dist/ai/docs/nocobase/ai-employees/knowledge-base/dev/external-knowledge-base.md

@@ -0,0 +1,318 @@
+---
+title: "External Knowledge Base plugin"
+description: "NocoBase knowledge base plugin development: register an external knowledge base provider, implement VectorStoreService, return RAG retrieval results, and configure external knowledge base parameters."
+keywords: "knowledge base plugin,External Knowledge Base,VectorStoreProvider,VectorStoreService,RAG,AI employees,NocoBase"
+---
+
+# External Knowledge Base plugin
+
+In NocoBase, a **External Knowledge Base plugin** extends the RAG retrieval sources available to AI employees. For most use cases, a Local knowledge base is enough. You only need an external knowledge base plugin when documents, vector data, or retrieval logic are already maintained by an external system.
+
+An external knowledge base plugin does not participate in document upload, segmentation, vectorization, or deletion in NocoBase. It only receives retrieval requests during AI employee conversations and returns matching document segments.
+
+:::tip Prereading
+
+- [Knowledge base overview](../knowledge-base/) - Understand the boundaries of Local, Readonly, and External knowledge bases
+- [Plugin](../../../plugin-development/server/plugin.md) - Understand server-side plugin lifecycle and `this.app.pm`
+- [i18n](../../../plugin-development/server/i18n.md) - Prepare translations if the plugin provides a configuration form
+
+:::
+
+## Use cases
+
+External knowledge bases are suitable for these cases:
+
+- You already have an independent RAG service, such as an internal knowledge base service or a third-party retrieval API
+- You need to connect to a vector database that NocoBase does not support out of the box
+- You need to process business rules before or after retrieval, such as permission checks, tenant isolation, reranking, or deduplication
+- The document lifecycle is fully maintained by an external system, and NocoBase only reads retrieval results during conversations
+
+If you only want to upload files in NocoBase, split documents automatically, and generate vector indexes, use a Local knowledge base by default.
+
+## Extension point
+
+External knowledge bases are registered through the `vectorStoreProvider` extension point provided by `@nocobase/plugin-ai`. The server side needs to implement two objects:
+
+| Object | Purpose |
+| --- | --- |
+| `VectorStoreProvider` | Declares the external knowledge base provider name and creates the retrieval service |
+| `VectorStoreService` | Performs retrieval and returns document segments that AI employees can use |
+
+`providerName` is the unique identifier of an external knowledge base provider. The provider selected or entered when creating an External knowledge base must match the `providerName` registered on the server side.
+
+## Register the Provider
+
+In `src/server/plugin.ts`, get the AI plugin instance and register your `VectorStoreProvider`:
+
+```ts
+import { Plugin } from '@nocobase/server';
+import PluginAIServer from '@nocobase/plugin-ai';
+import { MyExternalKnowledgeBaseProvider } from './vector-store/provider';
+
+export class PluginMyKnowledgeBaseServer extends Plugin {
+  async load() {
+    const aiPlugin = this.app.pm.get('ai') as PluginAIServer;
+
+    aiPlugin.features.vectorStoreProvider.register(new MyExternalKnowledgeBaseProvider());
+  }
+}
+
+export default PluginMyKnowledgeBaseServer;
+```
+
+The `load()` stage is suitable for registering extension points. You do not need to connect to the external vector database here, and retrieval requests should not be executed here. Put the actual connection and query logic in `VectorStoreService`.
+
+External knowledge base plugins always depend on `@nocobase/plugin-ai-knowledge-base`. It is recommended to check the dependency in `beforeEnable()`:
+
+```ts
+import { Plugin } from '@nocobase/server';
+
+export class PluginMyKnowledgeBaseServer extends Plugin {
+  async beforeEnable() {
+    const knowledgeBasePlugin = this.app.pm.get('ai-knowledge-base');
+
+    if (!knowledgeBasePlugin) {
+      throw new Error('Please enable @nocobase/plugin-ai-knowledge-base first.');
+    }
+  }
+}
+```
+
+This gives users a clear error message if the required plugin has not been enabled.
+
+## Implement the Provider
+
+The Provider only needs to provide `providerName` and create a service based on the knowledge base configuration.
+
+```ts
+import type { VectorStoreProp, VectorStoreProvider, VectorStoreService } from '@nocobase/plugin-ai';
+import { MyExternalKnowledgeBaseService } from './service';
+
+export class MyExternalKnowledgeBaseProvider implements VectorStoreProvider {
+  get providerName() {
+    return 'MyExternalKnowledgeBase';
+  }
+
+  async createVectorStoreService(vectorStoreProps?: VectorStoreProp[]): Promise<VectorStoreService> {
+    return new MyExternalKnowledgeBaseService(vectorStoreProps);
+  }
+}
+```
+
+`vectorStoreProps` comes from the external knowledge base configuration form, such as API endpoint, API key, Embedding model, tenant identifier, and similar parameters. NocoBase passes these values to the Provider when running retrieval.
+
+## Implement the Service
+
+The Service is the core retrieval logic. For an External knowledge base, it usually only needs to convert external retrieval results into the `DocumentSegmentedWithScore[]` format required by NocoBase.
+
+```ts
+import type {
+  DocumentSegmentedWithScore,
+  VectorStoreProp,
+  VectorStoreSearchOptions,
+  VectorStoreService,
+} from '@nocobase/plugin-ai';
+
+export class MyExternalKnowledgeBaseService implements VectorStoreService<unknown> {
+  constructor(private readonly vectorStoreProps?: VectorStoreProp[]) {}
+
+  async getVectorStore(): Promise<unknown> {
+    throw new Error('External knowledge base does not expose a NocoBase-managed vector store. Use search() instead.');
+  }
+
+  async search(query: string, options?: VectorStoreSearchOptions): Promise<DocumentSegmentedWithScore[]> {
+    const { topK, score } = options ?? {};
+    const endpoint = this.getPropValue('endpoint');
+    const apiKey = this.getPropValue('apiKey');
+
+    // You can connect to a vector database directly or call a third-party RAG service here.
+    const result = await this.searchExternalService({
+      query,
+      topK,
+      score,
+      endpoint,
+      apiKey,
+    });
+
+    return result.map((item) => ({
+      id: item.id,
+      content: item.content,
+      metadata: item.metadata,
+      score: item.score,
+    }));
+  }
+
+  private getPropValue(key: string): unknown {
+    return this.vectorStoreProps?.find((prop) => prop.key === key)?.value;
+  }
+
+  private async searchExternalService(params: {
+    query: string;
+    topK?: number;
+    score?: string;
+    endpoint: unknown;
+    apiKey: unknown;
+  }): Promise<DocumentSegmentedWithScore[]> {
+    // Replace this with your external service call.
+    return [];
+  }
+}
+```
+
+Key points:
+
+- **`query`** - The question that the AI employee needs to retrieve against
+- **`topK`** - The expected number of returned segments
+- **`score`** - The score threshold configured in the AI employee knowledge base settings
+- **`vectorStoreProps`** - Parameters filled in through the external knowledge base configuration form
+
+:::tip About `getVectorStore()`
+
+The `VectorStoreService` interface includes `getVectorStore()`. An External knowledge base is only responsible for retrieval and does not let NocoBase manage the underlying vector store, so the example throws an error directly.
+
+:::
+
+## Return retrieval results
+
+`search()` must return `DocumentSegmentedWithScore[]`:
+
+```ts
+type DocumentSegmentedWithScore = {
+  id?: string;
+  content: string;
+  metadata: Record<string, unknown>;
+  score: number;
+};
+```
+
+Where:
+
+- `content` is the document segment content passed to the large language model
+- `metadata` stores source, document title, URL, permission information, and other metadata
+- `score` is the retrieval score. It is recommended to normalize it so that a larger value means higher relevance
+- `id` identifies the external document segment, which helps with troubleshooting and deduplication
+
+If the external service uses a different score meaning, such as smaller distance meaning higher relevance, convert it to a consistent relevance score before returning it to NocoBase.
+
+## Configure external knowledge base parameters
+
+The server side can read `vectorStoreProps` directly, but these parameters usually need to be filled in when users create an External knowledge base. Therefore, the configuration form needs to be registered in the plugin frontend entry. After registration, NocoBase displays the corresponding fields in the knowledge base creation form and passes the values to the server side during retrieval.
+
+:::tip Note
+
+Frontend form configuration is optional. If your external knowledge base does not require custom parameters from users, you do not need to register `vectorStorePropForm`.
+
+:::
+
+For simple cases, use `defaultVectorStorePropForm()` by default. It receives an array of fields, creates one form item for each field, and uses an input that supports selecting NocoBase variables:
+
+| Parameter | Purpose |
+| --- | --- |
+| `key` | Field name used when saving the parameter and passing it to the server side |
+| `label` | Form item label |
+| `tooltip` | Form item tooltip |
+| `required` | Whether the field is required. If set, required validation is generated |
+| `password` | Whether to display the field as a password input, suitable for API keys and secrets |
+
+Register the configuration form in the plugin frontend entry:
+
+```tsx
+import { Plugin } from '@nocobase/client';
+import PluginAIClient, { defaultVectorStorePropForm } from '@nocobase/plugin-ai/client';
+
+export class PluginMyKnowledgeBaseClient extends Plugin {
+  async load() {
+    const aiPlugin = this.app.pm.get('ai') as PluginAIClient;
+
+    aiPlugin.features.vectorStoreProvider.register({
+      name: 'MyExternalKnowledgeBase',
+      title: String(this.t('My external knowledge base')),
+      components: {
+        vectorStorePropForm: defaultVectorStorePropForm([
+          {
+            key: 'endpoint',
+            label: String(this.t('Endpoint')),
+            required: true,
+          },
+          {
+            key: 'apiKey',
+            label: String(this.t('API key')),
+            required: true,
+            password: true,
+          },
+        ]),
+      },
+    });
+  }
+}
+```
+
+The `name` here must match the server-side `providerName`. The `key` is the field name used when saving the parameter and passing it to the server side. The server side can read the value from `vectorStoreProps` with the same key.
+
+### Custom configuration form
+
+Besides using `defaultVectorStorePropForm()`, you can also pass a custom React component to `vectorStorePropForm`:
+
+```tsx
+import { useFlowContext } from '@nocobase/flow-engine';
+import type { VectorStorePropFormValues } from '@nocobase/plugin-ai/client';
+import { Form, Input, Select } from 'antd';
+import type { FormInstance } from 'antd';
+
+const MyVectorStorePropForm = ({ form }: { form: FormInstance<VectorStorePropFormValues> }) => {
+  const ctx = useFlowContext();
+
+  return (
+    <Form form={form} layout="vertical" validateMessages={{ required: ctx.t('defaults.form.required') }}>
+      <Form.Item name="endpoint" label={String(ctx.t('Endpoint'))} rules={[{ required: true }]}>
+        <Input />
+      </Form.Item>
+      <Form.Item name="namespace" label={String(ctx.t('Namespace'))}>
+        <Input />
+      </Form.Item>
+      <Form.Item name="metric" label={String(ctx.t('Metric'))} initialValue="cosine">
+        <Select
+          options={[
+            { label: String(ctx.t('Cosine')), value: 'cosine' },
+            { label: String(ctx.t('L2')), value: 'l2' },
+          ]}
+        />
+      </Form.Item>
+    </Form>
+  );
+};
+
+aiPlugin.features.vectorStoreProvider.register({
+  name: 'MyExternalKnowledgeBase',
+  components: {
+    vectorStorePropForm: MyVectorStorePropForm,
+  },
+});
+```
+
+## Example plugin structure
+
+An external knowledge base plugin can be organized as follows:
+
+```text
+src/server/plugin.ts
+src/server/vector-store/provider.ts
+src/server/vector-store/service.ts
+src/client/index.tsx
+```
+
+Where:
+
+- `plugin.ts` registers `VectorStoreProvider`
+- `provider.ts` declares `providerName` and creates the service
+- `service.ts` implements `search()` and converts external retrieval results to `DocumentSegmentedWithScore[]`
+- `client/index.tsx` registers the external knowledge base configuration form
+
+At this point, the external knowledge base plugin can be called by AI employees. After users create an External knowledge base and select the corresponding Provider, AI employee conversations can retrieve document segments through your `search()`.
+
+## Related links
+
+- [Knowledge base overview](../knowledge-base/) - Boundaries of Local, Readonly, and External knowledge bases
+- [Plugin](../../../plugin-development/server/plugin.md) - Server-side plugin lifecycle and `this.app.pm`
+- [i18n](../../../plugin-development/server/i18n.md) - Plugin frontend and server-side translations
+- [Client plugin development overview](../../../plugin-development/client/index.md) - Client entry, components, and context capabilities

package/dist/ai/docs/nocobase/ai-employees/knowledge-base/knowledge-base/documents.md

@@ -0,0 +1,76 @@
+---
+pkg: "@nocobase/plugin-ai-knowledge-base"
+title: "Document management"
+description: "Upload documents, view status, run vectorization, download, or delete documents on the Documents page of a knowledge base."
+keywords: "knowledge base documents,document upload,vectorization,ZIP import,NocoBase"
+---
+
+# Document management
+
+## Open the Documents page
+
+After opening the knowledge base detail page, click Documents in the left sidebar. This page manages documents in the current knowledge base and is also the entry point for segment management.
+
+![](https://static-docs.nocobase.com/20260617004144.png)
+
+## Upload documents
+
+Click Upload in the upper-right corner to upload files. After upload, documents automatically enter segment generation and vectorization. Status first shows Pending, then changes to Success after processing. If processing fails, it shows Error, and an error icon appears next to the filename.
+
+Supported document types include: `txt`, `md`, `json`, `csv`, `xls`, `xlsx`, `pdf`, `doc`, `docx`, `ppt`, and `pptx`.
+
+:::tip PDF documents
+
+PDF only supports plain text content. If the PDF mainly contains scanned images, run OCR first and upload a file with extractable text.
+
+:::
+
+## Batch import
+
+To import multiple documents at once, package them as a ZIP file and upload it. NocoBase extracts the ZIP in the background and imports the documents into the current knowledge base.
+
+:::tip Upload size limit
+
+ZIP import is also limited by the upload size configured for the file storage. If the upload reports that the file is too large, adjust the limit in the File storage used by this knowledge base. See [File storage](../../../file-manager/storage/) for the related configuration.
+
+:::
+
+## View processing results
+
+Common fields in the document list:
+
+| Field | Meaning |
+| --- | --- |
+| Filename | Uploaded filename |
+| Status | Current vectorization status, usually Pending, Success, or Error |
+| Characters | Total number of enabled segment characters |
+| Segments | Number of segments generated from the document |
+| Created at / Updated at | Creation time and latest update time |
+
+If a document stays in Pending for a long time, click Refresh first. If it still does not finish, check background tasks, vector store, and LLM service availability.
+
+## Run vectorization
+
+After selecting documents in the list, click Vectorization above the list to rerun vectorization for the selected documents. If no document is selected, clicking Vectorization processes all documents in the current knowledge base.
+
+The row-level Vectorization action only processes the current document. It is usually used in these scenarios:
+
+- Vector store or vector database configuration changed
+- A document is in Error status and needs to be retried after the configuration is fixed
+- Segments were manually edited, disabled, or deleted, and the new vector data needs to take effect
+
+:::tip
+
+Editing, disabling, or deleting segments in segment management automatically triggers a new vectorization task. It is normal for the document status to briefly become Pending.
+
+:::
+
+## Download and delete
+
+Each row has three common actions:
+
+- Segments opens segment management for the current document
+- Download downloads the original document
+- Delete deletes the document and cleans up related segments and vector data
+
+The Delete button above the list deletes selected documents in batch. Deletion cannot be undone, so confirm the documents are no longer needed before deleting them.

package/dist/ai/docs/nocobase/ai-employees/knowledge-base/knowledge-base/hit-tests.md

@@ -0,0 +1,66 @@
+---
+pkg: "@nocobase/plugin-ai-knowledge-base"
+title: "Hit tests"
+description: "Enter test text on the Hit tests page and inspect matched document segments under Top K and Score settings."
+keywords: "knowledge base hit tests,Hit tests,Top K,Score,RAG,NocoBase"
+---
+
+# Hit tests
+
+## Open the Hit tests page
+
+After opening the knowledge base detail page, click Hit tests in the left sidebar. This page tests which document segments can be matched by a user input. It does not directly call AI employees and does not generate final answers.
+
+![](https://static-docs.nocobase.com/20260617005130.png)
+
+## Run a test
+
+Enter test text in the bottom input box, then click Send. NocoBase retrieves from the current knowledge base and shows matched segments by similarity from high to low.
+
+Each result card shows:
+
+- Match order
+- Document title
+- Similarity score
+- Segment preview
+- Source filename
+
+Click a result card to view fuller segment content, similarity score, and related questions matched in this test.
+
+![](https://static-docs.nocobase.com/20260617005408.png)
+
+If the current input does not match any segment, the page shows No matching documents found.
+
+![](https://static-docs.nocobase.com/20260617005636.png)
+
+## Adjust test parameters
+
+Click Settings in the upper-right corner to adjust parameters for this hit test.
+
+![](https://static-docs.nocobase.com/20260617005519.png)
+
+The settings are:
+
+- Top K: maximum number of matched segments to return
+- Score: minimum similarity threshold. Results below this value are filtered out
+
+Default parameters are `Top K = 4` and `Score = 0.6`. If there are too few results, lower Score or increase Top K. If results are too broad, increase Score.
+
+:::tip
+
+Adjust Top K and Score here to find suitable values before configuring knowledge base retrieval for an AI employee. These settings only affect the current hit test and are not written back to the AI employee. After confirming the values, enter the same parameters in the AI employee RAG settings. See [RAG retrieval](../rag) for details.
+
+:::
+
+## Adjust based on hit results
+
+Hit tests help determine whether the knowledge base is ready for RAG.
+
+Common adjustments:
+
+- Target document is not matched: check whether vectorization succeeded, or lower Score to see weakly related results
+- Irrelevant content is matched: increase Score, or disable/delete noisy segments
+- Matched content is too long or too short: return to Segments, adjust segmentation parameters, and regenerate segments
+- Common user phrasings are not matched: add Related questions in segment details
+
+After modifying segments, wait for vectorization to finish, then return to Hit tests and test again.

package/dist/ai/docs/nocobase/ai-employees/knowledge-base/knowledge-base/index.md

@@ -0,0 +1,73 @@
+---
+pkg: "@nocobase/plugin-ai-knowledge-base"
+title: "Overview"
+description: "Use a knowledge base to organize documents, generate segments and vector indexes, and provide maintainable data sources for AI employee RAG retrieval."
+keywords: "knowledge base,AI knowledge base,RAG,document management,vector index,NocoBase"
+---
+
+# Overview
+
+## Introduction
+
+A knowledge base is the foundation of RAG retrieval. You can add product manuals, internal policies, business terminology, FAQs, and other documents to a knowledge base. NocoBase converts these documents into searchable segments and vector data. When an AI employee answers a question, it can retrieve related content from the knowledge base first, then send that content to the model as context.
+
+For most scenarios, a Local knowledge base is enough. Only consider Readonly or External knowledge bases when documents and vector data are already maintained by an external system.
+
+![](https://static-docs.nocobase.com/20260617003643.png)
+
+## Open knowledge base management
+
+Open the AI employees plugin configuration page and click the Knowledge base tab to view the knowledge base list. Each card shows the knowledge base name, document count, character count, number of AI employee references, and enabled status.
+
+Click a knowledge base card to open its detail page:
+
+- Documents is used to upload documents, run vectorization, and open segment management
+- Hit tests is used to test which segments can be matched by a query
+- Settings is used to adjust basic information, vector store, and default segmentation parameters
+
+![](https://static-docs.nocobase.com/20260617004104.png)
+
+## Create a knowledge base
+
+Click Add new in the upper-right corner to create a knowledge base. The menu shows three types: Local, Readonly, and External.
+
+![](https://static-docs.nocobase.com/20260617003505.png)
+
+The three knowledge base types have different capability boundaries:
+
+| Type | Use case |
+| --- | --- |
+| Local | Documents, segment files, and vector data are managed by NocoBase. It supports uploading documents in the UI, and also supports creating, updating, deleting, and retrieving knowledge base documents through workflow nodes |
+| Readonly | Documents and vector data are maintained by an external system. NocoBase cannot maintain this data in the UI or workflows, and only uses the knowledge base as a RAG retrieval source. Currently, PGVector is the only supported vector database |
+| External | Documents, vector data, and retrieval logic are all handled by an external system. NocoBase cannot directly maintain documents or vector data. Developers need to provide a plugin and implement the retrieval logic in that plugin, such as connecting to a vector database not yet supported by NocoBase or calling a third-party retrieval API. For development details, see [External Knowledge Base plugin](../dev/external-knowledge-base) |
+
+Local knowledge bases are recommended by default. Only consider Readonly or External when documents and vector data are already maintained outside NocoBase and NocoBase only needs to read retrieval results.
+
+A Local knowledge base usually needs the following information:
+
+![](https://static-docs.nocobase.com/20260617003603.png)
+
+- Key: unique identifier of the knowledge base. It cannot be changed after creation
+- Name: knowledge base name
+- File storage: where original documents and segment files are stored
+- Vector store: vector store used to generate and retrieve vectors
+- Description: knowledge base description
+- Split document, Chunk size, and Chunk overlap: default segmentation parameters used after document upload
+- Enabled: whether the knowledge base is enabled
+
+:::tip Prerequisites
+
+Before creating a Local knowledge base, prepare two dependencies: file storage for original documents and segment files, see [File storage](../../../file-manager/storage/); and vector storage for generating and retrieving vectors, see [Vector database](../vector-database) and [Vector store](../vector-store).
+
+:::
+
+## Next steps
+
+| I want to... | Where to go |
+| --- | --- |
+| Upload files, view vectorization status, and rerun vectorization | [Document management](./documents) |
+| View, edit, disable, or delete document segments | [Segment management](./segments) |
+| Test which segments a question can match | [Hit tests](./hit-tests) |
+| Modify knowledge base information and default segmentation settings | [Settings](./settings) |
+
+At this point, the knowledge base is ready to be connected to RAG. You can enable knowledge base retrieval in AI employee settings. See [RAG retrieval](../rag) for details.

package/dist/ai/docs/nocobase/ai-employees/knowledge-base/knowledge-base/segments.md

@@ -0,0 +1,93 @@
+---
+pkg: "@nocobase/plugin-ai-knowledge-base"
+title: "Segment management"
+description: "Open the Segments dialog from the Documents page to view, edit, disable, delete, and regenerate document segments."
+keywords: "knowledge base segments,Segments,Chunk size,Chunk overlap,related questions,NocoBase"
+---
+
+# Segment management
+
+After a document is uploaded, NocoBase first splits the body into segments according to the segmentation parameters, then writes enabled segments into the vector store. RAG retrieval matches these segments, not the original whole document. Split document, Chunk size, and Chunk overlap affect the number of segments, context length, and continuity between adjacent segments.
+
+## Open segment management
+
+Open the knowledge base Documents page, then click Segments on the right side of a document. The Segment management dialog shows all segments generated for the current document.
+
+![](https://static-docs.nocobase.com/20260617004439.png)
+
+## View the segment list
+
+The segment list shows:
+
+| Field | Meaning |
+| --- | --- |
+| No. | Segment number, starting from 1 |
+| Preview | Segment content preview |
+| Characters | Character count of the current segment |
+| Related questions | Number of related questions configured for the current segment |
+| Enabled | Whether the segment participates in vectorization and retrieval |
+| Updated at | Latest segment update time |
+
+After Enabled only is turned on, the list only shows enabled segments. This switch only affects display and does not modify segment data.
+
+:::tip Historical data note
+
+If a document was uploaded with an earlier version of the knowledge base plugin, its segment information may not have been saved separately. Earlier versions of the knowledge base plugin stored segment content and segment vectors together in the vector database, so the segment list in Segment management may be empty.
+
+This does not affect knowledge base retrieval. You only need to run vectorization again or regenerate segments if you need to view or edit the segment list. Usually, you do not need to reprocess documents only to make data appear in the list.
+
+:::
+
+## Edit a segment
+
+Click Edit on the right side of a segment to open its detail view.
+
+![](https://static-docs.nocobase.com/20260617004531.png)
+
+You can edit:
+
+- Content: segment body
+- Related questions: additional searchable phrasings
+
+:::tip Related questions
+
+Related questions are used to add common phrasings for the current segment. They do not rewrite the segment body, but they participate in vector retrieval. If a user question closely matches a related question, the retrieval result returns the document segment associated with that related question.
+
+:::
+
+After saving, NocoBase updates the segment file and triggers vectorization for the current document. When you return to the Documents list, the status may briefly show Pending.
+
+## Enable, disable, and delete segments
+
+The Enabled switch controls whether a single segment participates in retrieval:
+
+- Enabled: the segment is written to the vector store and can be retrieved by RAG and hit tests
+- Disabled: the segment remains in the list but does not participate in later vectorization or retrieval
+
+Click Delete to delete the current segment and its vector data. After deletion, the document segment count and character count are recalculated.
+
+:::warning Note
+
+Disabling or deleting a segment triggers vectorization again. Before processing finishes, the document status may show Pending.
+
+:::
+
+## Regenerate segments
+
+Click Segment settings in the upper-right corner to reset segmentation parameters for the current document.
+
+![](https://static-docs.nocobase.com/20260617004702.png)
+
+The settings are:
+
+- Split document: whether to split the document according to the parameters. When enabled, multiple segments are generated; when disabled, the whole document is used as one segment
+- Chunk size: maximum number of characters in each segment, default `6000`. Smaller values create finer segments; larger values keep more context in a single matched result
+- Chunk overlap: number of overlapping characters kept between adjacent segments, default `1200`. A reasonable overlap reduces context breaks at segment boundaries
+
+Click Resegment to regenerate segments with the current parameters.
+
+:::warning Note
+
+Regenerating segments discards manually edited segment content and related questions. Only run this action when you are sure the document should be rebuilt with new parameters.
+
+:::