跳至内容

索引

基础索引类。

BaseIndex #

基类: Generic[IS], ABC

LlamaIndex基础。

参数:

名称 类型 描述 默认值
nodes List[Node]

待索引的节点列表

None
show_progress bool

是否显示tqdm进度条。默认为False。

False
Source code in llama-index-core/llama_index/core/indices/base.py
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
class BaseIndex(Generic[IS], ABC):
    """
    Base LlamaIndex.

    Args:
        nodes (List[Node]): List of nodes to index
        show_progress (bool): Whether to show tqdm progress bars. Defaults to False.

    """

    index_struct_cls: Type[IS]

    def __init__(
        self,
        nodes: Optional[Sequence[BaseNode]] = None,
        objects: Optional[Sequence[IndexNode]] = None,
        index_struct: Optional[IS] = None,
        storage_context: Optional[StorageContext] = None,
        callback_manager: Optional[CallbackManager] = None,
        transformations: Optional[List[TransformComponent]] = None,
        show_progress: bool = False,
        **kwargs: Any,
    ) -> None:
        """Initialize with parameters."""
        if index_struct is None and nodes is None and objects is None:
            raise ValueError("One of nodes, objects, or index_struct must be provided.")
        if index_struct is not None and nodes is not None and len(nodes) >= 1:
            raise ValueError("Only one of nodes or index_struct can be provided.")
        # This is to explicitly make sure that the old UX is not used
        if nodes is not None and len(nodes) >= 1 and not isinstance(nodes[0], BaseNode):
            if isinstance(nodes[0], Document):
                raise ValueError(
                    "The constructor now takes in a list of Node objects. "
                    "Since you are passing in a list of Document objects, "
                    "please use `from_documents` instead."
                )
            else:
                raise ValueError("nodes must be a list of Node objects.")

        self._storage_context = storage_context or StorageContext.from_defaults()
        self._docstore = self._storage_context.docstore
        self._show_progress = show_progress
        self._vector_store = self._storage_context.vector_store
        self._graph_store = self._storage_context.graph_store
        self._callback_manager = callback_manager or Settings.callback_manager

        objects = objects or []
        self._object_map = {obj.index_id: obj.obj for obj in objects}
        for obj in objects:
            obj.obj = None  # clear the object to avoid serialization issues

        with self._callback_manager.as_trace("index_construction"):
            if index_struct is None:
                nodes = nodes or []
                index_struct = self.build_index_from_nodes(
                    nodes + objects,  # type: ignore
                    **kwargs,  # type: ignore
                )
            self._index_struct = index_struct
            self._storage_context.index_store.add_index_struct(self._index_struct)

        self._transformations = transformations or Settings.transformations

    @classmethod
    def from_documents(
        cls: Type[IndexType],
        documents: Sequence[Document],
        storage_context: Optional[StorageContext] = None,
        show_progress: bool = False,
        callback_manager: Optional[CallbackManager] = None,
        transformations: Optional[List[TransformComponent]] = None,
        **kwargs: Any,
    ) -> IndexType:
        """
        Create index from documents.

        Args:
            documents (Sequence[Document]]): List of documents to
                build the index from.

        """
        storage_context = storage_context or StorageContext.from_defaults()
        docstore = storage_context.docstore
        callback_manager = callback_manager or Settings.callback_manager
        transformations = transformations or Settings.transformations

        with callback_manager.as_trace("index_construction"):
            for doc in documents:
                docstore.set_document_hash(doc.get_doc_id(), doc.hash)

            nodes = run_transformations(
                documents,  # type: ignore
                transformations,
                show_progress=show_progress,
                **kwargs,
            )

            return cls(
                nodes=nodes,
                storage_context=storage_context,
                callback_manager=callback_manager,
                show_progress=show_progress,
                transformations=transformations,
                **kwargs,
            )

    @property
    def index_struct(self) -> IS:
        """Get the index struct."""
        return self._index_struct

    @property
    def index_id(self) -> str:
        """Get the index struct."""
        return self._index_struct.index_id

    def set_index_id(self, index_id: str) -> None:
        """
        Set the index id.

        NOTE: if you decide to set the index_id on the index_struct manually,
        you will need to explicitly call `add_index_struct` on the `index_store`
        to update the index store.

        Args:
            index_id (str): Index id to set.

        """
        # delete the old index struct
        old_id = self._index_struct.index_id
        self._storage_context.index_store.delete_index_struct(old_id)
        # add the new index struct
        self._index_struct.index_id = index_id
        self._storage_context.index_store.add_index_struct(self._index_struct)

    @property
    def docstore(self) -> BaseDocumentStore:
        """Get the docstore corresponding to the index."""
        return self._docstore

    @property
    def storage_context(self) -> StorageContext:
        return self._storage_context

    @property
    def summary(self) -> str:
        return str(self._index_struct.summary)

    @summary.setter
    def summary(self, new_summary: str) -> None:
        self._index_struct.summary = new_summary
        self._storage_context.index_store.add_index_struct(self._index_struct)

    @abstractmethod
    def _build_index_from_nodes(
        self, nodes: Sequence[BaseNode], **build_kwargs: Any
    ) -> IS:
        """Build the index from nodes."""

    def build_index_from_nodes(
        self, nodes: Sequence[BaseNode], **build_kwargs: Any
    ) -> IS:
        """Build the index from nodes."""
        self._docstore.add_documents(nodes, allow_update=True)
        return self._build_index_from_nodes(nodes, **build_kwargs)

    @abstractmethod
    def _insert(self, nodes: Sequence[BaseNode], **insert_kwargs: Any) -> None:
        """Index-specific logic for inserting nodes to the index struct."""

    def insert_nodes(self, nodes: Sequence[BaseNode], **insert_kwargs: Any) -> None:
        """Insert nodes."""
        for node in nodes:
            if isinstance(node, IndexNode):
                try:
                    node.dict()
                except ValueError:
                    self._object_map[node.index_id] = node.obj
                    node.obj = None

        with self._callback_manager.as_trace("insert_nodes"):
            self.docstore.add_documents(nodes, allow_update=True)
            self._insert(nodes, **insert_kwargs)
            self._storage_context.index_store.add_index_struct(self._index_struct)

    async def ainsert_nodes(
        self, nodes: Sequence[BaseNode], **insert_kwargs: Any
    ) -> None:
        """Asynchronously insert nodes."""
        for node in nodes:
            if isinstance(node, IndexNode):
                try:
                    node.dict()
                except ValueError:
                    self._object_map[node.index_id] = node.obj
                    node.obj = None

        with self._callback_manager.as_trace("ainsert_nodes"):
            await self.docstore.async_add_documents(nodes, allow_update=True)
            self._insert(nodes=nodes)
            await self._storage_context.index_store.async_add_index_struct(
                self._index_struct
            )

    def insert(self, document: Document, **insert_kwargs: Any) -> None:
        """Insert a document."""
        with self._callback_manager.as_trace("insert"):
            nodes = run_transformations(
                [document],
                self._transformations,
                show_progress=self._show_progress,
                **insert_kwargs,
            )

            self.insert_nodes(nodes, **insert_kwargs)
            self.docstore.set_document_hash(document.get_doc_id(), document.hash)

    async def ainsert(self, document: Document, **insert_kwargs: Any) -> None:
        """Asynchronously insert a document."""
        with self._callback_manager.as_trace("ainsert"):
            nodes = await arun_transformations(
                [document],
                self._transformations,
                show_progress=self._show_progress,
                **insert_kwargs,
            )

            await self.ainsert_nodes(nodes, **insert_kwargs)
            await self.docstore.aset_document_hash(document.get_doc_id(), document.hash)

    @abstractmethod
    def _delete_node(self, node_id: str, **delete_kwargs: Any) -> None:
        """Delete a node."""

    def delete_nodes(
        self,
        node_ids: List[str],
        delete_from_docstore: bool = False,
        **delete_kwargs: Any,
    ) -> None:
        """
        Delete a list of nodes from the index.

        Args:
            doc_ids (List[str]): A list of doc_ids from the nodes to delete

        """
        for node_id in node_ids:
            self._delete_node(node_id, **delete_kwargs)
            if delete_from_docstore:
                self.docstore.delete_document(node_id, raise_error=False)

        self._storage_context.index_store.add_index_struct(self._index_struct)

    async def adelete_nodes(
        self,
        node_ids: List[str],
        delete_from_docstore: bool = False,
        **delete_kwargs: Any,
    ) -> None:
        """
        Asynchronously delete a list of nodes from the index.

        Args:
            doc_ids (List[str]): A list of doc_ids from the nodes to delete

        """
        for node_id in node_ids:
            self._delete_node(node_id, **delete_kwargs)
            if delete_from_docstore:
                await self.docstore.adelete_document(node_id, raise_error=False)

        await self._storage_context.index_store.async_add_index_struct(
            self._index_struct
        )

    def delete(self, doc_id: str, **delete_kwargs: Any) -> None:
        """
        Delete a document from the index.
        All nodes in the index related to the index will be deleted.

        Args:
            doc_id (str): A doc_id of the ingested document

        """
        logger.warning(
            "delete() is now deprecated, please refer to delete_ref_doc() to delete "
            "ingested documents+nodes or delete_nodes to delete a list of nodes."
            "Use adelete_ref_docs() for an asynchronous implementation"
        )
        self.delete_ref_doc(doc_id)

    def delete_ref_doc(
        self, ref_doc_id: str, delete_from_docstore: bool = False, **delete_kwargs: Any
    ) -> None:
        """Delete a document and it's nodes by using ref_doc_id."""
        ref_doc_info = self.docstore.get_ref_doc_info(ref_doc_id)
        if ref_doc_info is None:
            logger.warning(f"ref_doc_id {ref_doc_id} not found, nothing deleted.")
            return

        self.delete_nodes(
            ref_doc_info.node_ids,
            delete_from_docstore=False,
            **delete_kwargs,
        )

        if delete_from_docstore:
            self.docstore.delete_ref_doc(ref_doc_id, raise_error=False)

    async def adelete_ref_doc(
        self, ref_doc_id: str, delete_from_docstore: bool = False, **delete_kwargs: Any
    ) -> None:
        """Delete a document and it's nodes by using ref_doc_id."""
        ref_doc_info = await self.docstore.aget_ref_doc_info(ref_doc_id)
        if ref_doc_info is None:
            logger.warning(f"ref_doc_id {ref_doc_id} not found, nothing deleted.")
            return

        await self.adelete_nodes(
            ref_doc_info.node_ids,
            delete_from_docstore=False,
            **delete_kwargs,
        )

        if delete_from_docstore:
            await self.docstore.adelete_ref_doc(ref_doc_id, raise_error=False)

    def update(self, document: Document, **update_kwargs: Any) -> None:
        """
        Update a document and it's corresponding nodes.

        This is equivalent to deleting the document and then inserting it again.

        Args:
            document (Union[BaseDocument, BaseIndex]): document to update
            insert_kwargs (Dict): kwargs to pass to insert
            delete_kwargs (Dict): kwargs to pass to delete

        """
        logger.warning(
            "update() is now deprecated, please refer to update_ref_doc() to update "
            "ingested documents+nodes."
            "Use aupdate_ref_docs() for an asynchronous implementation"
        )
        self.update_ref_doc(document, **update_kwargs)

    def update_ref_doc(self, document: Document, **update_kwargs: Any) -> None:
        """
        Update a document and it's corresponding nodes.

        This is equivalent to deleting the document and then inserting it again.

        Args:
            document (Union[BaseDocument, BaseIndex]): document to update
            insert_kwargs (Dict): kwargs to pass to insert
            delete_kwargs (Dict): kwargs to pass to delete

        """
        with self._callback_manager.as_trace("update_ref_doc"):
            self.delete_ref_doc(
                document.get_doc_id(),
                delete_from_docstore=True,
                **update_kwargs.pop("delete_kwargs", {}),
            )
            self.insert(document, **update_kwargs.pop("insert_kwargs", {}))

    async def aupdate_ref_doc(self, document: Document, **update_kwargs: Any) -> None:
        """
        Asynchronously update a document and it's corresponding nodes.

        This is equivalent to deleting the document and then inserting it again.

        Args:
            document (Union[BaseDocument, BaseIndex]): document to update
            insert_kwargs (Dict): kwargs to pass to insert
            delete_kwargs (Dict): kwargs to pass to delete

        """
        with self._callback_manager.as_trace("aupdate_ref_doc"):
            await self.adelete_ref_doc(
                document.get_doc_id(),
                delete_from_docstore=True,
                **update_kwargs.pop("delete_kwargs", {}),
            )
            await self.ainsert(document, **update_kwargs.pop("insert_kwargs", {}))

    def refresh(
        self, documents: Sequence[Document], **update_kwargs: Any
    ) -> List[bool]:
        """
        Refresh an index with documents that have changed.

        This allows users to save LLM and Embedding model calls, while only
        updating documents that have any changes in text or metadata. It
        will also insert any documents that previously were not stored.
        """
        logger.warning(
            "refresh() is now deprecated, please refer to refresh_ref_docs() to "
            "refresh ingested documents+nodes with an updated list of documents."
            "Use arefresh_ref_docs() for an asynchronous implementation"
        )
        return self.refresh_ref_docs(documents, **update_kwargs)

    def refresh_ref_docs(
        self, documents: Sequence[Document], **update_kwargs: Any
    ) -> List[bool]:
        """
        Refresh an index with documents that have changed.

        This allows users to save LLM and Embedding model calls, while only
        updating documents that have any changes in text or metadata. It
        will also insert any documents that previously were not stored.
        """
        with self._callback_manager.as_trace("refresh_ref_docs"):
            refreshed_documents = [False] * len(documents)
            for i, document in enumerate(documents):
                existing_doc_hash = self._docstore.get_document_hash(
                    document.get_doc_id()
                )
                if existing_doc_hash is None:
                    self.insert(document, **update_kwargs.pop("insert_kwargs", {}))
                    refreshed_documents[i] = True
                elif existing_doc_hash != document.hash:
                    self.update_ref_doc(
                        document, **update_kwargs.pop("update_kwargs", {})
                    )
                    refreshed_documents[i] = True

            return refreshed_documents

    async def arefresh_ref_docs(
        self, documents: Sequence[Document], **update_kwargs: Any
    ) -> List[bool]:
        """
        Asynchronously refresh an index with documents that have changed.

        This allows users to save LLM and Embedding model calls, while only
        updating documents that have any changes in text or metadata. It
        will also insert any documents that previously were not stored.
        """
        with self._callback_manager.as_trace("arefresh_ref_docs"):
            refreshed_documents = [False] * len(documents)
            for i, document in enumerate(documents):
                existing_doc_hash = await self._docstore.aget_document_hash(
                    document.get_doc_id()
                )
                if existing_doc_hash is None:
                    await self.ainsert(
                        document, **update_kwargs.pop("insert_kwargs", {})
                    )
                    refreshed_documents[i] = True
                elif existing_doc_hash != document.hash:
                    await self.aupdate_ref_doc(
                        document, **update_kwargs.pop("update_kwargs", {})
                    )
                    refreshed_documents[i] = True
            return refreshed_documents

    @property
    @abstractmethod
    def ref_doc_info(self) -> Dict[str, RefDocInfo]:
        """Retrieve a dict mapping of ingested documents and their nodes+metadata."""
        ...

    @abstractmethod
    def as_retriever(self, **kwargs: Any) -> BaseRetriever: ...

    def as_query_engine(
        self, llm: Optional[LLMType] = None, **kwargs: Any
    ) -> BaseQueryEngine:
        """
        Convert the index to a query engine.

        Calls `index.as_retriever(**kwargs)` to get the retriever and then wraps it in a
        `RetrieverQueryEngine.from_args(retriever, **kwrags)` call.
        """
        # NOTE: lazy import
        from llama_index.core.query_engine.retriever_query_engine import (
            RetrieverQueryEngine,
        )

        retriever = self.as_retriever(**kwargs)
        llm = (
            resolve_llm(llm, callback_manager=self._callback_manager)
            if llm
            else Settings.llm
        )

        return RetrieverQueryEngine.from_args(
            retriever,
            llm=llm,
            **kwargs,
        )

    def as_chat_engine(
        self,
        chat_mode: ChatMode = ChatMode.BEST,
        llm: Optional[LLMType] = None,
        **kwargs: Any,
    ) -> BaseChatEngine:
        """
        Convert the index to a chat engine.

        Calls `index.as_query_engine(llm=llm, **kwargs)` to get the query engine and then
        wraps it in a chat engine based on the chat mode.

        Chat modes:
            - `ChatMode.BEST` (default): Chat engine that uses an agent (react or openai) with a query engine tool
            - `ChatMode.CONTEXT`: Chat engine that uses a retriever to get context
            - `ChatMode.CONDENSE_QUESTION`: Chat engine that condenses questions
            - `ChatMode.CONDENSE_PLUS_CONTEXT`: Chat engine that condenses questions and uses a retriever to get context
            - `ChatMode.SIMPLE`: Simple chat engine that uses the LLM directly
            - `ChatMode.REACT`: Chat engine that uses a react agent with a query engine tool
            - `ChatMode.OPENAI`: Chat engine that uses an openai agent with a query engine tool
        """
        llm = (
            resolve_llm(llm, callback_manager=self._callback_manager)
            if llm
            else Settings.llm
        )

        query_engine = self.as_query_engine(llm=llm, **kwargs)

        # resolve chat mode
        if chat_mode in [ChatMode.REACT, ChatMode.OPENAI, ChatMode.BEST]:
            # use an agent with query engine tool in these chat modes
            # NOTE: lazy import
            from llama_index.core.agent import AgentRunner
            from llama_index.core.tools.query_engine import QueryEngineTool

            # convert query engine to tool
            query_engine_tool = QueryEngineTool.from_defaults(query_engine=query_engine)

            return AgentRunner.from_llm(
                tools=[query_engine_tool],
                llm=llm,
                **kwargs,
            )

        if chat_mode == ChatMode.CONDENSE_QUESTION:
            # NOTE: lazy import
            from llama_index.core.chat_engine import CondenseQuestionChatEngine

            return CondenseQuestionChatEngine.from_defaults(
                query_engine=query_engine,
                llm=llm,
                **kwargs,
            )
        elif chat_mode == ChatMode.CONTEXT:
            from llama_index.core.chat_engine import ContextChatEngine

            return ContextChatEngine.from_defaults(
                retriever=self.as_retriever(**kwargs),
                llm=llm,
                **kwargs,
            )

        elif chat_mode == ChatMode.CONDENSE_PLUS_CONTEXT:
            from llama_index.core.chat_engine import CondensePlusContextChatEngine

            return CondensePlusContextChatEngine.from_defaults(
                retriever=self.as_retriever(**kwargs),
                llm=llm,
                **kwargs,
            )

        elif chat_mode == ChatMode.SIMPLE:
            from llama_index.core.chat_engine import SimpleChatEngine

            return SimpleChatEngine.from_defaults(
                llm=llm,
                **kwargs,
            )
        else:
            raise ValueError(f"Unknown chat mode: {chat_mode}")

索引结构 property #

index_struct: IS

获取索引结构。

索引ID property #

index_id: str

获取索引结构。

文档存储 property #

获取与索引对应的文档存储。

ref_doc_info abstractmethod property #

ref_doc_info: Dict[str, RefDocInfo]

获取已摄取文档及其节点+元数据的字典映射。

from_documents classmethod #

from_documents(documents: Sequence[Document], storage_context: Optional[StorageContext] = None, show_progress: bool = False, callback_manager: Optional[CallbackManager] = None, transformations: Optional[List[TransformComponent]] = None, **kwargs: Any) -> IndexType

从文档创建索引。

参数:

名称 类型 描述 默认值
documents Sequence[Document]]

用于构建索引的文档列表。

required
Source code in llama-index-core/llama_index/core/indices/base.py
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
@classmethod
def from_documents(
    cls: Type[IndexType],
    documents: Sequence[Document],
    storage_context: Optional[StorageContext] = None,
    show_progress: bool = False,
    callback_manager: Optional[CallbackManager] = None,
    transformations: Optional[List[TransformComponent]] = None,
    **kwargs: Any,
) -> IndexType:
    """
    Create index from documents.

    Args:
        documents (Sequence[Document]]): List of documents to
            build the index from.

    """
    storage_context = storage_context or StorageContext.from_defaults()
    docstore = storage_context.docstore
    callback_manager = callback_manager or Settings.callback_manager
    transformations = transformations or Settings.transformations

    with callback_manager.as_trace("index_construction"):
        for doc in documents:
            docstore.set_document_hash(doc.get_doc_id(), doc.hash)

        nodes = run_transformations(
            documents,  # type: ignore
            transformations,
            show_progress=show_progress,
            **kwargs,
        )

        return cls(
            nodes=nodes,
            storage_context=storage_context,
            callback_manager=callback_manager,
            show_progress=show_progress,
            transformations=transformations,
            **kwargs,
        )

set_index_id #

set_index_id(index_id: str) -> None

设置索引ID。

注意:如果您决定手动在index_struct上设置index_id,您需要显式调用add_index_struct来更新索引存储。

参数:

名称 类型 描述 默认值
index_id str

要设置的索引ID。

required
Source code in llama-index-core/llama_index/core/indices/base.py
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
def set_index_id(self, index_id: str) -> None:
    """
    Set the index id.

    NOTE: if you decide to set the index_id on the index_struct manually,
    you will need to explicitly call `add_index_struct` on the `index_store`
    to update the index store.

    Args:
        index_id (str): Index id to set.

    """
    # delete the old index struct
    old_id = self._index_struct.index_id
    self._storage_context.index_store.delete_index_struct(old_id)
    # add the new index struct
    self._index_struct.index_id = index_id
    self._storage_context.index_store.add_index_struct(self._index_struct)

从节点构建索引 #

build_index_from_nodes(nodes: Sequence[BaseNode], **build_kwargs: Any) -> IS

从节点构建索引。

Source code in llama-index-core/llama_index/core/indices/base.py
184
185
186
187
188
189
def build_index_from_nodes(
    self, nodes: Sequence[BaseNode], **build_kwargs: Any
) -> IS:
    """Build the index from nodes."""
    self._docstore.add_documents(nodes, allow_update=True)
    return self._build_index_from_nodes(nodes, **build_kwargs)

insert_nodes #

insert_nodes(nodes: Sequence[BaseNode], **insert_kwargs: Any) -> None

插入节点。

Source code in llama-index-core/llama_index/core/indices/base.py
195
196
197
198
199
200
201
202
203
204
205
206
207
208
def insert_nodes(self, nodes: Sequence[BaseNode], **insert_kwargs: Any) -> None:
    """Insert nodes."""
    for node in nodes:
        if isinstance(node, IndexNode):
            try:
                node.dict()
            except ValueError:
                self._object_map[node.index_id] = node.obj
                node.obj = None

    with self._callback_manager.as_trace("insert_nodes"):
        self.docstore.add_documents(nodes, allow_update=True)
        self._insert(nodes, **insert_kwargs)
        self._storage_context.index_store.add_index_struct(self._index_struct)

ainsert_nodes async #

ainsert_nodes(nodes: Sequence[BaseNode], **insert_kwargs: Any) -> None

异步插入节点。

Source code in llama-index-core/llama_index/core/indices/base.py
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
async def ainsert_nodes(
    self, nodes: Sequence[BaseNode], **insert_kwargs: Any
) -> None:
    """Asynchronously insert nodes."""
    for node in nodes:
        if isinstance(node, IndexNode):
            try:
                node.dict()
            except ValueError:
                self._object_map[node.index_id] = node.obj
                node.obj = None

    with self._callback_manager.as_trace("ainsert_nodes"):
        await self.docstore.async_add_documents(nodes, allow_update=True)
        self._insert(nodes=nodes)
        await self._storage_context.index_store.async_add_index_struct(
            self._index_struct
        )

插入 #

insert(document: Document, **insert_kwargs: Any) -> None

插入文档。

Source code in llama-index-core/llama_index/core/indices/base.py
229
230
231
232
233
234
235
236
237
238
239
240
def insert(self, document: Document, **insert_kwargs: Any) -> None:
    """Insert a document."""
    with self._callback_manager.as_trace("insert"):
        nodes = run_transformations(
            [document],
            self._transformations,
            show_progress=self._show_progress,
            **insert_kwargs,
        )

        self.insert_nodes(nodes, **insert_kwargs)
        self.docstore.set_document_hash(document.get_doc_id(), document.hash)

ainsert async #

ainsert(document: Document, **insert_kwargs: Any) -> None

异步插入文档。

Source code in llama-index-core/llama_index/core/indices/base.py
242
243
244
245
246
247
248
249
250
251
252
253
async def ainsert(self, document: Document, **insert_kwargs: Any) -> None:
    """Asynchronously insert a document."""
    with self._callback_manager.as_trace("ainsert"):
        nodes = await arun_transformations(
            [document],
            self._transformations,
            show_progress=self._show_progress,
            **insert_kwargs,
        )

        await self.ainsert_nodes(nodes, **insert_kwargs)
        await self.docstore.aset_document_hash(document.get_doc_id(), document.hash)

delete_nodes #

delete_nodes(node_ids: List[str], delete_from_docstore: bool = False, **delete_kwargs: Any) -> None

从索引中删除一组节点。

参数:

名称 类型 描述 默认值
doc_ids List[str]

要删除的节点对应的doc_id列表

required
Source code in llama-index-core/llama_index/core/indices/base.py
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
def delete_nodes(
    self,
    node_ids: List[str],
    delete_from_docstore: bool = False,
    **delete_kwargs: Any,
) -> None:
    """
    Delete a list of nodes from the index.

    Args:
        doc_ids (List[str]): A list of doc_ids from the nodes to delete

    """
    for node_id in node_ids:
        self._delete_node(node_id, **delete_kwargs)
        if delete_from_docstore:
            self.docstore.delete_document(node_id, raise_error=False)

    self._storage_context.index_store.add_index_struct(self._index_struct)

adelete_nodes async #

adelete_nodes(node_ids: List[str], delete_from_docstore: bool = False, **delete_kwargs: Any) -> None

异步从索引中删除一组节点。

参数:

名称 类型 描述 默认值
doc_ids List[str]

要删除的节点对应的文档ID列表

required
Source code in llama-index-core/llama_index/core/indices/base.py
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
async def adelete_nodes(
    self,
    node_ids: List[str],
    delete_from_docstore: bool = False,
    **delete_kwargs: Any,
) -> None:
    """
    Asynchronously delete a list of nodes from the index.

    Args:
        doc_ids (List[str]): A list of doc_ids from the nodes to delete

    """
    for node_id in node_ids:
        self._delete_node(node_id, **delete_kwargs)
        if delete_from_docstore:
            await self.docstore.adelete_document(node_id, raise_error=False)

    await self._storage_context.index_store.async_add_index_struct(
        self._index_struct
    )

删除 #

delete(doc_id: str, **delete_kwargs: Any) -> None

从索引中删除一个文档。与该索引相关的所有节点将被删除。

参数:

名称 类型 描述 默认值
doc_id str

已摄取文档的doc_id

required
Source code in llama-index-core/llama_index/core/indices/base.py
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
def delete(self, doc_id: str, **delete_kwargs: Any) -> None:
    """
    Delete a document from the index.
    All nodes in the index related to the index will be deleted.

    Args:
        doc_id (str): A doc_id of the ingested document

    """
    logger.warning(
        "delete() is now deprecated, please refer to delete_ref_doc() to delete "
        "ingested documents+nodes or delete_nodes to delete a list of nodes."
        "Use adelete_ref_docs() for an asynchronous implementation"
    )
    self.delete_ref_doc(doc_id)

delete_ref_doc #

delete_ref_doc(ref_doc_id: str, delete_from_docstore: bool = False, **delete_kwargs: Any) -> None

通过使用ref_doc_id删除文档及其节点。

Source code in llama-index-core/llama_index/core/indices/base.py
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
def delete_ref_doc(
    self, ref_doc_id: str, delete_from_docstore: bool = False, **delete_kwargs: Any
) -> None:
    """Delete a document and it's nodes by using ref_doc_id."""
    ref_doc_info = self.docstore.get_ref_doc_info(ref_doc_id)
    if ref_doc_info is None:
        logger.warning(f"ref_doc_id {ref_doc_id} not found, nothing deleted.")
        return

    self.delete_nodes(
        ref_doc_info.node_ids,
        delete_from_docstore=False,
        **delete_kwargs,
    )

    if delete_from_docstore:
        self.docstore.delete_ref_doc(ref_doc_id, raise_error=False)

adelete_ref_doc async #

adelete_ref_doc(ref_doc_id: str, delete_from_docstore: bool = False, **delete_kwargs: Any) -> None

通过使用ref_doc_id删除文档及其节点。

Source code in llama-index-core/llama_index/core/indices/base.py
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
async def adelete_ref_doc(
    self, ref_doc_id: str, delete_from_docstore: bool = False, **delete_kwargs: Any
) -> None:
    """Delete a document and it's nodes by using ref_doc_id."""
    ref_doc_info = await self.docstore.aget_ref_doc_info(ref_doc_id)
    if ref_doc_info is None:
        logger.warning(f"ref_doc_id {ref_doc_id} not found, nothing deleted.")
        return

    await self.adelete_nodes(
        ref_doc_info.node_ids,
        delete_from_docstore=False,
        **delete_kwargs,
    )

    if delete_from_docstore:
        await self.docstore.adelete_ref_doc(ref_doc_id, raise_error=False)

更新 #

update(document: Document, **update_kwargs: Any) -> None

更新文档及其对应的节点。

这相当于删除文档后重新插入。

参数:

名称 类型 描述 默认值
document Union[BaseDocument, BaseIndex]

待更新的文档

required
insert_kwargs Dict

传递给插入的kwargs参数

required
delete_kwargs Dict

传递给删除的kwargs参数

required
Source code in llama-index-core/llama_index/core/indices/base.py
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
def update(self, document: Document, **update_kwargs: Any) -> None:
    """
    Update a document and it's corresponding nodes.

    This is equivalent to deleting the document and then inserting it again.

    Args:
        document (Union[BaseDocument, BaseIndex]): document to update
        insert_kwargs (Dict): kwargs to pass to insert
        delete_kwargs (Dict): kwargs to pass to delete

    """
    logger.warning(
        "update() is now deprecated, please refer to update_ref_doc() to update "
        "ingested documents+nodes."
        "Use aupdate_ref_docs() for an asynchronous implementation"
    )
    self.update_ref_doc(document, **update_kwargs)

update_ref_doc #

update_ref_doc(document: Document, **update_kwargs: Any) -> None

更新文档及其对应的节点。

这相当于删除文档后重新插入。

参数:

名称 类型 描述 默认值
document Union[BaseDocument, BaseIndex]

待更新的文档

required
insert_kwargs Dict

传递给插入的kwargs参数

required
delete_kwargs Dict

传递给删除的kwargs参数

required
Source code in llama-index-core/llama_index/core/indices/base.py
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
def update_ref_doc(self, document: Document, **update_kwargs: Any) -> None:
    """
    Update a document and it's corresponding nodes.

    This is equivalent to deleting the document and then inserting it again.

    Args:
        document (Union[BaseDocument, BaseIndex]): document to update
        insert_kwargs (Dict): kwargs to pass to insert
        delete_kwargs (Dict): kwargs to pass to delete

    """
    with self._callback_manager.as_trace("update_ref_doc"):
        self.delete_ref_doc(
            document.get_doc_id(),
            delete_from_docstore=True,
            **update_kwargs.pop("delete_kwargs", {}),
        )
        self.insert(document, **update_kwargs.pop("insert_kwargs", {}))

aupdate_ref_doc async #

aupdate_ref_doc(document: Document, **update_kwargs: Any) -> None

异步更新文档及其对应的节点。

这相当于删除文档后重新插入。

参数:

名称 类型 描述 默认值
document Union[BaseDocument, BaseIndex]

待更新的文档

required
insert_kwargs Dict

传递给插入的kwargs参数

required
delete_kwargs Dict

传递给删除的关键字参数

required
Source code in llama-index-core/llama_index/core/indices/base.py
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
async def aupdate_ref_doc(self, document: Document, **update_kwargs: Any) -> None:
    """
    Asynchronously update a document and it's corresponding nodes.

    This is equivalent to deleting the document and then inserting it again.

    Args:
        document (Union[BaseDocument, BaseIndex]): document to update
        insert_kwargs (Dict): kwargs to pass to insert
        delete_kwargs (Dict): kwargs to pass to delete

    """
    with self._callback_manager.as_trace("aupdate_ref_doc"):
        await self.adelete_ref_doc(
            document.get_doc_id(),
            delete_from_docstore=True,
            **update_kwargs.pop("delete_kwargs", {}),
        )
        await self.ainsert(document, **update_kwargs.pop("insert_kwargs", {}))

刷新 #

refresh(documents: Sequence[Document], **update_kwargs: Any) -> List[bool]

使用已更改的文档刷新索引。

这允许用户节省LLM和Embedding模型的调用,仅更新文本或元数据发生变化的文档。同时它还会插入之前未存储的任何文档。

Source code in llama-index-core/llama_index/core/indices/base.py
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
def refresh(
    self, documents: Sequence[Document], **update_kwargs: Any
) -> List[bool]:
    """
    Refresh an index with documents that have changed.

    This allows users to save LLM and Embedding model calls, while only
    updating documents that have any changes in text or metadata. It
    will also insert any documents that previously were not stored.
    """
    logger.warning(
        "refresh() is now deprecated, please refer to refresh_ref_docs() to "
        "refresh ingested documents+nodes with an updated list of documents."
        "Use arefresh_ref_docs() for an asynchronous implementation"
    )
    return self.refresh_ref_docs(documents, **update_kwargs)

refresh_ref_docs #

refresh_ref_docs(documents: Sequence[Document], **update_kwargs: Any) -> List[bool]

使用已更改的文档刷新索引。

这允许用户节省LLM和嵌入模型的调用次数,仅更新文本或元数据发生变化的文档。同时,它还会插入之前未存储的任何文档。

Source code in llama-index-core/llama_index/core/indices/base.py
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
def refresh_ref_docs(
    self, documents: Sequence[Document], **update_kwargs: Any
) -> List[bool]:
    """
    Refresh an index with documents that have changed.

    This allows users to save LLM and Embedding model calls, while only
    updating documents that have any changes in text or metadata. It
    will also insert any documents that previously were not stored.
    """
    with self._callback_manager.as_trace("refresh_ref_docs"):
        refreshed_documents = [False] * len(documents)
        for i, document in enumerate(documents):
            existing_doc_hash = self._docstore.get_document_hash(
                document.get_doc_id()
            )
            if existing_doc_hash is None:
                self.insert(document, **update_kwargs.pop("insert_kwargs", {}))
                refreshed_documents[i] = True
            elif existing_doc_hash != document.hash:
                self.update_ref_doc(
                    document, **update_kwargs.pop("update_kwargs", {})
                )
                refreshed_documents[i] = True

        return refreshed_documents

arefresh_ref_docs async #

arefresh_ref_docs(documents: Sequence[Document], **update_kwargs: Any) -> List[bool]

异步刷新索引以包含已更改的文档。

这允许用户节省LLM和嵌入模型的调用次数,仅更新文本或元数据发生变化的文档。同时,它还会插入之前未存储的任何文档。

Source code in llama-index-core/llama_index/core/indices/base.py
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
async def arefresh_ref_docs(
    self, documents: Sequence[Document], **update_kwargs: Any
) -> List[bool]:
    """
    Asynchronously refresh an index with documents that have changed.

    This allows users to save LLM and Embedding model calls, while only
    updating documents that have any changes in text or metadata. It
    will also insert any documents that previously were not stored.
    """
    with self._callback_manager.as_trace("arefresh_ref_docs"):
        refreshed_documents = [False] * len(documents)
        for i, document in enumerate(documents):
            existing_doc_hash = await self._docstore.aget_document_hash(
                document.get_doc_id()
            )
            if existing_doc_hash is None:
                await self.ainsert(
                    document, **update_kwargs.pop("insert_kwargs", {})
                )
                refreshed_documents[i] = True
            elif existing_doc_hash != document.hash:
                await self.aupdate_ref_doc(
                    document, **update_kwargs.pop("update_kwargs", {})
                )
                refreshed_documents[i] = True
        return refreshed_documents

as_query_engine #

as_query_engine(llm: Optional[LLMType] = None, **kwargs: Any) -> BaseQueryEngine

将索引转换为查询引擎。

调用index.as_retriever(**kwargs)获取检索器,然后将其封装在RetrieverQueryEngine.from_args(retriever, **kwrags)调用中。

Source code in llama-index-core/llama_index/core/indices/base.py
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
def as_query_engine(
    self, llm: Optional[LLMType] = None, **kwargs: Any
) -> BaseQueryEngine:
    """
    Convert the index to a query engine.

    Calls `index.as_retriever(**kwargs)` to get the retriever and then wraps it in a
    `RetrieverQueryEngine.from_args(retriever, **kwrags)` call.
    """
    # NOTE: lazy import
    from llama_index.core.query_engine.retriever_query_engine import (
        RetrieverQueryEngine,
    )

    retriever = self.as_retriever(**kwargs)
    llm = (
        resolve_llm(llm, callback_manager=self._callback_manager)
        if llm
        else Settings.llm
    )

    return RetrieverQueryEngine.from_args(
        retriever,
        llm=llm,
        **kwargs,
    )

作为聊天引擎 #

as_chat_engine(chat_mode: ChatMode = BEST, llm: Optional[LLMType] = None, **kwargs: Any) -> BaseChatEngine

将索引转换为聊天引擎。

调用index.as_query_engine(llm=llm, **kwargs)获取查询引擎,然后根据聊天模式将其封装为聊天引擎。

Chat modes
  • ChatMode.BEST (默认): 使用带有查询引擎工具的智能体(react或openai)的聊天引擎
  • ChatMode.CONTEXT: 使用检索器获取上下文的聊天引擎
  • ChatMode.CONDENSE_QUESTION: 能够精简问题的聊天引擎
  • ChatMode.CONDENSE_PLUS_CONTEXT: 能够压缩问题并使用检索器获取上下文的聊天引擎
  • ChatMode.SIMPLE: 直接使用LLM的简单聊天引擎
  • ChatMode.REACT: 使用带有查询引擎工具的react智能体的聊天引擎
  • ChatMode.OPENAI: 使用带有查询引擎工具的openai智能体的聊天引擎
Source code in llama-index-core/llama_index/core/indices/base.py
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
def as_chat_engine(
    self,
    chat_mode: ChatMode = ChatMode.BEST,
    llm: Optional[LLMType] = None,
    **kwargs: Any,
) -> BaseChatEngine:
    """
    Convert the index to a chat engine.

    Calls `index.as_query_engine(llm=llm, **kwargs)` to get the query engine and then
    wraps it in a chat engine based on the chat mode.

    Chat modes:
        - `ChatMode.BEST` (default): Chat engine that uses an agent (react or openai) with a query engine tool
        - `ChatMode.CONTEXT`: Chat engine that uses a retriever to get context
        - `ChatMode.CONDENSE_QUESTION`: Chat engine that condenses questions
        - `ChatMode.CONDENSE_PLUS_CONTEXT`: Chat engine that condenses questions and uses a retriever to get context
        - `ChatMode.SIMPLE`: Simple chat engine that uses the LLM directly
        - `ChatMode.REACT`: Chat engine that uses a react agent with a query engine tool
        - `ChatMode.OPENAI`: Chat engine that uses an openai agent with a query engine tool
    """
    llm = (
        resolve_llm(llm, callback_manager=self._callback_manager)
        if llm
        else Settings.llm
    )

    query_engine = self.as_query_engine(llm=llm, **kwargs)

    # resolve chat mode
    if chat_mode in [ChatMode.REACT, ChatMode.OPENAI, ChatMode.BEST]:
        # use an agent with query engine tool in these chat modes
        # NOTE: lazy import
        from llama_index.core.agent import AgentRunner
        from llama_index.core.tools.query_engine import QueryEngineTool

        # convert query engine to tool
        query_engine_tool = QueryEngineTool.from_defaults(query_engine=query_engine)

        return AgentRunner.from_llm(
            tools=[query_engine_tool],
            llm=llm,
            **kwargs,
        )

    if chat_mode == ChatMode.CONDENSE_QUESTION:
        # NOTE: lazy import
        from llama_index.core.chat_engine import CondenseQuestionChatEngine

        return CondenseQuestionChatEngine.from_defaults(
            query_engine=query_engine,
            llm=llm,
            **kwargs,
        )
    elif chat_mode == ChatMode.CONTEXT:
        from llama_index.core.chat_engine import ContextChatEngine

        return ContextChatEngine.from_defaults(
            retriever=self.as_retriever(**kwargs),
            llm=llm,
            **kwargs,
        )

    elif chat_mode == ChatMode.CONDENSE_PLUS_CONTEXT:
        from llama_index.core.chat_engine import CondensePlusContextChatEngine

        return CondensePlusContextChatEngine.from_defaults(
            retriever=self.as_retriever(**kwargs),
            llm=llm,
            **kwargs,
        )

    elif chat_mode == ChatMode.SIMPLE:
        from llama_index.core.chat_engine import SimpleChatEngine

        return SimpleChatEngine.from_defaults(
            llm=llm,
            **kwargs,
        )
    else:
        raise ValueError(f"Unknown chat mode: {chat_mode}")