LLamaIndex - 构建全栈Web应用程序的指南

本文翻译整理自：A Guide to Building a Full-Stack Web App with LLamaIndex
https://docs.llamaindex.ai/en/stable/understanding/putting_it_all_together/apps/fullstack_app_guide/

文章目录

- 简介
- 一、Flask 后端
- - 基本Flask - 处理用户索引查询
  - Advanced Flask - 处理用户文档上传
  - - `index_server.py`
    - `index_server.py`
    - `flask_demo.py`
- 二、React前端
- - fetchDocuments.tsx
  - queryIndex.tsx
  - insertDocument.tsx
  - 所有其他前端好
- 结论

简介

LlamaIndex是一个python库，这意味着将其与全栈Web应用程序集成将与您可能习惯的有点不同。

本指南旨在介绍创建用python编写的基本API服务所需的步骤，以及它如何与TypeScript+React前端交互。

这里的所有代码示例都可以从flask_react文件夹中的llama_index_starter_pack获得。

本指南中使用的主要技术如下：

python 3.11
llama_index
Flask
typescript
React

一、Flask 后端

对于本指南，我们的后端将使用FlaskAPI服务器与我们的前端代码通信。如果您愿意，您也可以轻松地将其转换为FastAPI服务器或您选择的任何其他python服务器库。

使用Flask设置服务器很容易。您导入包，创建应用程序对象，然后创建端点。让我们先为服务器创建一个基本框架：

from flask import Flaskapp = Flask(__name__)@app.route("/")
def home():return "Hello World!"if __name__ == "__main__":app.run(host="0.0.0.0", port=5601)

flask_demo.py

如果您运行此文件（python flask_demo.py），它将在端口5601上启动服务器。如果您访问http://localhost:5601/，您将看到浏览器中呈现的“Hello World！”文本。不错！

下一步是决定我们想要在服务器中包含哪些函数，并开始使用LlamaIndex。

为了简单起见，我们可以提供的最基本操作是查询现有索引。使用LlamaIndex的paul graham文章，创建一个文档文件夹并下载+放置其中的文章文本文件。

基本Flask - 处理用户索引查询

现在，让我们编写一些代码来初始化我们的索引：

import os
from llama_index.core import (SimpleDirectoryReader,VectorStoreIndex,StorageContext,load_index_from_storage,
)# NOTE: for local testing only, do NOT deploy with your key hardcoded
os.environ["OPENAI_API_KEY"] = "your key here"index = Nonedef initialize_index():global indexstorage_context = StorageContext.from_defaults()index_dir = "./.index"if os.path.exists(index_dir):index = load_index_from_storage(storage_context)else:documents = SimpleDirectoryReader("./documents").load_data()index = VectorStoreIndex.from_documents(documents, storage_context=storage_context)storage_context.persist(index_dir)

这个函数将初始化我们的索引。如果我们在main函数中启动Flask 服务器之前调用它，那么我们的索引将准备好供用户查询！

我们的查询端点将接受以查询文本作为参数的GET请求。完整的端点函数如下所示：

from flask import request@app.route("/query", methods=["GET"])
def query_index():global indexquery_text = request.args.get("text", None)if query_text is None:return ("No text found, please include a ?text=blah parameter in the URL",400,)query_engine = index.as_query_engine()response = query_engine.query(query_text)return str(response), 200

现在，我们为我们的服务器引入了一些新概念：

由函数装饰器定义的新/query端点
来自Flask 的新导入request，用于从请求中获取参数
如果缺少text参数，则返回错误消息和适当的 HTML 响应代码
否则，我们查询索引，并将响应作为字符串返回

您可以在浏览器中测试的完整查询示例可能如下所示：http://localhost:5601/query?text=what did the author do growing up（一旦您按回车键，浏览器将把空格转换为“%20”字符）。

事情看起来很好！我们现在有了一个功能性API。使用您自己的文档，您可以轻松地为任何应用程序提供一个接口来调用Flask API并获得查询答案。

Advanced Flask - 处理用户文档上传

事情看起来很酷，但我们如何更进一步？如果我们想让用户通过上传自己的文档来构建自己的索引怎么办？别害怕，Flask可以处理这一切：肌肉：。

为了让用户上传文档，我们必须采取一些额外的预防措施。索引将变为可变的，而不是查询现有索引。如果您有许多用户添加到同一个索引，我们需要考虑如何处理并发。我们的Flask服务器是线程化的，这意味着多个用户可以使用将同时处理的请求ping服务器。

一种选择可能是为每个用户或组创建一个索引，并从S3存储和获取内容。但是对于这个例子，我们将假设有一个用户正在与之交互的本地存储索引。

为了处理并发上传并确保顺序插入到索引中，我们可以使用BaseManagerpython包来使用单独的服务器和锁提供对索引的顺序访问。这听起来很可怕，但也没那么糟糕！我们将把所有索引操作（初始化、查询、插入）移动到BaseManager“index_server”中，它将从我们的Flask服务器调用。

下面是我们移动代码后index_server.py的基本示例：

`index_server.py`

import os
from multiprocessing import Lock
from multiprocessing.managers import BaseManager
from llama_index.core import SimpleDirectoryReader, VectorStoreIndex, Document# NOTE: for local testing only, do NOT deploy with your key hardcoded
os.environ["OPENAI_API_KEY"] = "your key here"index = None
lock = Lock()def initialize_index():global indexwith lock:# same as before ...passdef query_index(query_text):global indexquery_engine = index.as_query_engine()response = query_engine.query(query_text)return str(response)if __name__ == "__main__":# init the global indexprint("initializing index...")initialize_index()# setup server# NOTE: you might want to handle the password in a less hardcoded waymanager = BaseManager(("", 5602), b"password")manager.register("query_index", query_index)server = manager.get_server()print("starting server...")server.serve_forever()

`index_server.py`

因此，我们移动了我们的函数，引入了Lock对象，它确保了对全局索引的顺序访问，在服务器中注册了我们的单个函数，并在端口5602上使用密码password启动了服务器。

然后，我们可以如下调整我们的Flask 代码：

from multiprocessing.managers import BaseManager
from flask import Flask, request# initialize manager connection
# NOTE: you might want to handle the password in a less hardcoded way
manager = BaseManager(("", 5602), b"password")
manager.register("query_index")
manager.connect()@app.route("/query", methods=["GET"])
def query_index():global indexquery_text = request.args.get("text", None)if query_text is None:return ("No text found, please include a ?text=blah parameter in the URL",400,)response = manager.query_index(query_text)._getvalue()return str(response), 200@app.route("/")
def home():return "Hello World!"if __name__ == "__main__":app.run(host="0.0.0.0", port=5601)

`flask_demo.py`

两个主要变化是连接到我们现有的BaseManager服务器并注册函数，以及通过/query端点中的管理器调用函数。

需要特别注意的是，BaseManager服务器不会像我们预期的那样返回对象。要将返回值解析为原始对象，我们调用_getvalue()函数。

如果我们允许用户上传他们自己的文档，我们可能应该从文档文件夹中删除Paul Graham的文章，所以让我们先这样做。然后，让我们添加一个端点来上传文件！首先，让我们定义我们的Flask端点函数：

...
manager.register("insert_into_index")
...@app.route("/uploadFile", methods=["POST"])
def upload_file():global managerif "file" not in request.files:return "Please send a POST request with a file", 400filepath = Nonetry:uploaded_file = request.files["file"]filename = secure_filename(uploaded_file.filename)filepath = os.path.join("documents", os.path.basename(filename))uploaded_file.save(filepath)if request.form.get("filename_as_doc_id", None) is not None:manager.insert_into_index(filepath, doc_id=filename)else:manager.insert_into_index(filepath)except Exception as e:# cleanup temp fileif filepath is not None and os.path.exists(filepath):os.remove(filepath)return "Error: {}".format(str(e)), 500# cleanup temp fileif filepath is not None and os.path.exists(filepath):os.remove(filepath)return "File inserted!", 200

还不错！你会注意到我们将文件写入磁盘。如果我们只接受基本的文件格式，如txt文件，我们可以跳过这一点，但是写入磁盘，我们可以利用LlamaIndex的SimpleDirectoryReader来处理一堆更复杂的文件格式。或者，我们还使用第二个POST参数来使用文件名作为doc_id或者让LlamaIndex为我们生成一个。一旦我们实现前端，这将更有意义。

对于这些更复杂的请求，我还建议使用像Postman这样的工具。使用postman测试端点的示例在这个项目的存储库中。

最后，您会注意到我们为Manager添加了一个新函数。让我们在index_server.py中实现它：

def insert_into_index(doc_text, doc_id=None):global indexdocument = SimpleDirectoryReader(input_files=[doc_text]).load_data()[0]if doc_id is not None:document.doc_id = doc_idwith lock:index.insert(document)index.storage_context.persist()...
manager.register("insert_into_index", insert_into_index)
...

简单！如果我们启动index_server.py和flask_demo.py的python文件，我们就有了一个Flask API服务器，可以处理多个请求，将文档插入矢量索引并响应用户查询！

为了支持前端的一些功能，我调整了Flask API的一些响应，并添加了一些功能来跟踪哪些文档存储在索引中（LlamaIndex目前不支持用户友好的方式，但我们可以自己增强它！）。最后，我必须使用Flask-corspython包向服务器添加CORS支持。

查看存储库中的完整flask_demo.py和index_server.py脚本以获取最后的小更改、requirements.txt文件和示例Dockerfile以帮助部署。

二、React前端

一般来说，React和Typescript是当今编写webapp最流行的库和语言之一。本指南将假定您熟悉这些工具的工作原理，因为否则本指南的长度将增加三倍：微笑：。

在存储库中，前端代码被组织在react_frontend文件夹内。

前端最相关的部分将是src/apis文件夹。这是我们调用Flask服务器的地方，支持以下查询：

/query–对现有索引进行查询
/uploadFile–将文件上传到Flask 服务器以插入索引
/getDocuments–列出当前文档标题及其部分文本

使用这三个查询，我们可以构建一个健壮的前端，允许用户上传和跟踪他们的文件、查询索引、查看查询响应以及有关使用哪些文本节点来形成响应的信息。

fetchDocuments.tsx

您猜对了，该文件包含获取索引中当前文档列表的函数。代码如下：

export type Document = {id: string;text: string;
};const fetchDocuments = async (): Promise<Document[]> => {const response = await fetch("http://localhost:5601/getDocuments", {mode: "cors",});if (!response.ok) {return [];}const documentList = (await response.json()) as Document[];return documentList;
};

如您所见，我们对Flask服务器进行了查询（这里，它假定在localhost上运行）。请注意，我们需要包含mode: 'cors'选项，因为我们正在发出外部请求。

然后，我们检查响应是否可以，如果可以，则获取响应json并返回它。在这里，响应json是在同一文件中定义的Document对象的列表。

queryIndex.tsx

该文件将用户查询发送到Flask 服务器，并取回响应，以及有关我们索引中哪些节点提供了响应的详细信息。

export type ResponseSources = {text: string;doc_id: string;start: number;end: number;similarity: number;
};export type QueryResponse = {text: string;sources: ResponseSources[];
};const queryIndex = async (query: string): Promise<QueryResponse> => {const queryURL = new URL("http://localhost:5601/query?text=1");queryURL.searchParams.append("text", query);const response = await fetch(queryURL, { mode: "cors" });if (!response.ok) {return { text: "Error in query", sources: [] };}const queryResponse = (await response.json()) as QueryResponse;return queryResponse;
};export default queryIndex;

这类似于fetchDocuments.tsx文件，主要区别在于我们将查询文本作为参数包含在URL中。然后，我们检查响应是否正常，并使用适当的typescript类型返回它。

insertDocument.tsx

可能最复杂的API调用是上传文档。这里的函数接受一个文件对象，并使用FormData构造一个POST请求。

实际的响应文本未在应用程序中使用，但可用于就文件是否上传失败提供一些用户反馈。

const insertDocument = async (file: File) => {const formData = new FormData();formData.append("file", file);formData.append("filename_as_doc_id", "true");const response = await fetch("http://localhost:5601/uploadFile", {mode: "cors",method: "POST",body: formData,});const responseText = response.text();return responseText;
};export default insertDocument;