入门教程（使用OpenAI）#

本教程将展示如何开始使用LlamaIndex构建智能体。我们将从一个基础示例开始，然后演示如何添加RAG（检索增强生成）功能。

Tip

请确保已按照安装指南完成环境配置。

Tip

想使用本地模型？若希望完全基于本地模型完成入门教程，请参阅此替代教程。

设置OpenAI API密钥#

LlamaIndex默认使用OpenAI的gpt-3.5-turbo模型。请通过环境变量设置API密钥：

# MacOS/Linux
export OPENAI_API_KEY=XXXXX

# Windows
set OPENAI_API_KEY=XXXXX

Tip

如果使用OpenAI兼容API，可使用OpenAILike LLM类。更多信息请参考OpenAILike LLM集成和OpenAILike Embeddings集成文档。

基础智能体示例#

我们从调用工具实现基础乘法运算的简单智能体开始。创建名为starter.py的文件：

import asyncio
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI


# 定义简易计算器工具
def multiply(a: float, b: float) -> float:
    """用于两个数字的乘法运算"""
    return a * b


# 创建包含计算器工具的智能体工作流
agent = FunctionAgent(
    tools=[multiply],
    llm=OpenAI(model="gpt-4o-mini"),
    system_prompt="你是一个能进行数字乘法运算的助手",
)


async def main():
    # 运行智能体
    response = await agent.run("1234乘以4567等于多少？")
    print(str(response))


# 执行智能体
if __name__ == "__main__":
    asyncio.run(main())

运行后将输出类似结果：\( 1234 \times 4567 \) 的结果是 \( 5,678,678 \)

其工作原理如下：

智能体接收问题：1234乘以4567等于多少？
系统内部将该问题与工具模式（名称、文档字符串、参数）传递给LLM
智能体选择multiply工具并生成工具参数
智能体接收工具返回结果并整合到最终响应中

Tip

如你所见，我们使用async异步函数。多数LLM和模型支持异步调用，推荐使用异步代码提升应用性能。了解更多异步编程知识，推荐阅读Python异步编程简章。

添加聊天历史记录#

AgentWorkflow能够记忆历史消息，这些信息存储在Context对象中。

传入Context后，智能体会基于上下文继续对话：

from llama_index.core.workflow import Context

# 创建上下文
ctx = Context(agent)

# 携带上下文运行智能体
response = await agent.run("我叫Logan", ctx=ctx)
response = await agent.run("我的名字是什么？", ctx=ctx)

添加RAG功能#

现在为智能体增加文档检索能力。首先通过终端获取示例数据：

mkdir data
wget https://raw.githubusercontent.com/run-llama/llama_index/main/docs/docs/examples/data/paul_graham/paul_graham_essay.txt -O data/paul_graham_essay.txt

目录结构应如下所示：

├── starter.py
└── data
    └── paul_graham_essay.txt

接下来创建基于LlamaIndex的文档检索工具。默认情况下，VectorStoreIndex会使用OpenAI的text-embedding-ada-002模型进行文本嵌入和检索。

修改后的starter.py如下：

from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI
import asyncio
import os

# 创建LlamaIndex文档检索工具
documents = SimpleDirectoryReader("data").load_data()
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()


def multiply(a: float, b: float) -> float:
    """用于两个数字的乘法运算"""
    return a * b


async def search_documents(query: str) -> str:
    """用于回答关于Paul Graham个人文章的自然语言问题"""
    response = await query_engine.aquery(query)
    return str(response)


# 创建包含双重功能的增强型工作流
agent = FunctionAgent(
    tools=[multiply, search_documents],
    llm=OpenAI(model="gpt-4o-mini"),
    system_prompt="""你是一个能进行数学计算
    并通过文档检索回答问题的智能助手""",
)


# 现在可以同时提问文档内容和进行数学计算
async def main():
    response = await agent.run(
        "作者在大学期间做了什么？另外7乘以8等于多少？"
    )
    print(response)


# 运行智能体
if __name__ == "__main__":
    asyncio.run(main())

现在智能体可以无缝切换使用计算器和文档检索功能来回答问题。

存储RAG索引#

为避免每次重新处理文档，可将索引持久化存储：

# 保存索引
index.storage_context.persist("storage")

# 后续加载索引
from llama_index.core import StorageContext, load_index_from_storage

storage_context = StorageContext.from_defaults(persist_dir="storage")
index = load_index_from_storage(storage_context)
query_engine = index.as_query_engine()

Tip

如果使用了非默认向量存储集成，通常可直接从向量存储重新加载：

index = VectorStoreIndex.from_vector_store(vector_store)

后续步骤#

这只是LlamaIndex智能体功能的开端！你还可以：

为智能体添加更多工具
使用不同LLM模型
通过系统提示定制智能体行为
添加流式处理能力
实现人机协同工作流
使用多智能体协作完成任务