llama_index_starter_pack的Flask API深度拆解：文档上传、查询、列表3大接口（附Postman实测）
llama_index_starter_pack的Flask API深度拆解文档上传、查询、列表3大接口附Postman实测【免费下载链接】llama_index_starter_packThis repository provides very basic flask, streamlit, and docker examples for the llama_index (fka gpt_index) package项目地址: https://gitcode.com/gh_mirrors/ll/llama_index_starter_packllama_index_starter_pack是新手入门llama_index曾用名 gpt_index向量索引包的最佳起点其中最实用的就是flask_react目录下的Flask API 示例一个不到 100 行代码的 Flask RAG检索增强生成服务提供文档上传、语义查询、文档列表3 大接口请求/响应格式清晰配合 Postman 即可完整体验上传文档 → 自然语言提问 → 带引用来源回答的全流程。先看整体架构两个进程、三个端口这个示例把HTTP 接口层和向量索引层拆成了两个独立进程这是理解整个 Flask API 的关键进程源码文件端口职责索引服务flask_react/index_server.py5602持有全局向量索引提供查询/插入/文档列表 3 个能力Flask APIflask_react/flask_demo.py5601对外暴露 3 个 HTTP 接口把请求转发给索引服务React 前端flask_react/react_frontend/3000调用上述 3 个 API 的可视化演示页面为什么要拆两个进程作者在flask_react/index_server.py中用multiprocessing.Lock保护索引写入——因为 Flask 是多线程的而插入文档是可变操作直接写在 Flask 里会产生并发问题。Flask 端通过multiprocessing.managers.BaseManager连接到 5602 端口的索引服务见flask_react/flask_demo.py第 11-16 行本身不碰索引只做参数校验和 JSON 封装。接口一语义查询接口 /queryGET这是 3 个接口中最核心的一个负责自然语言提问 → 从索引检索 → LLM 生成回答。请求方式GET /query?textWhat did the author do growing up?参数说明text必填查询文本缺少时返回 400 错误响应格式JSON{ text: AI 生成的回答, sources: [ { text: 命中的原文片段, similarity: 0.74, doc_id: profile_cover_letter.txt, start: 0, end: 2010 } ] }sources数组是 RAG 的精髓每个来源片段都带有相似度分数、文档 ID和在原文中的起止位置前端可以直接渲染成回答 引用出处。核心逻辑见flask_react/flask_demo.py第 19-36 行的query_index()函数真正调用index.as_query_engine().query()的地方在flask_react/index_server.py第 35-39 行。下面这张 Postman 截图展示了如何用curl/GET 方式实测该接口flask_react/postman_examples/query_example.jpg接口二文档上传接口 /uploadFilePOST请求方式multipart/form-dataKEYVALUE说明file文本/PDF 文件必填filename_as_doc_idtrue可选以文件名作为文档 ID成功返回 200 和文本File inserted!失败返回 500并自动清理临时文件flask_react/flask_demo.py第 39-66 行。上传后发生的完整链路flask_react/index_server.py第 42-59 行SimpleDirectoryReader读取文件内容支持 PDF 依赖pypdfindex.insert(document)将文档切分并写入向量索引index.storage_context.persist()把索引持久化到./saved_index目录重启服务后索引不会丢用 pickle 记录文档前 200 字摘要供文档列表接口使用React 前端调用该接口的方式可参考flask_react/react_frontend/src/apis/insertDocument.tsx。接口三文档列表接口 /getDocumentsGET请求方式GET /getDocuments响应格式JSON 数组[ { id: paul_graham_essay.txt, text: 文章前 200 字预览... } ]这里有个值得学习的细节llama_index 本身没有提供列出所有已存文档的便捷 API作者因此在flask_react/index_server.py第 61-68 行的get_documents_list()中用独立的 pickle 文件stored_documents.pkl自维护了一份文档 ID → 前 200 字的映射弥补了框架的空缺。前端封装见flask_react/react_frontend/src/apis/fetchDocuments.tsx。Postman 实测3 步验证接口 推荐用 Postman 按以下顺序测试项目自带截图示例目录flask_react/postman_examples/先调GET /getDocuments—— 新环境下应返回空数组[]再调POST /uploadFile—— 以 form-data 上传flask_react/documents/paul_graham_essay.txt示例自带的保罗·格雷厄姆经典文章确认返回File inserted!最后调GET /query?textWhat did the author do growing up?—— 观察text回答与sources引用similarity越接近 1 表示检索片段越相关提示GET /根路径会返回Hello, World! Welcome to the llama_index docker image!可用作服务存活探针。如何跑起来3 步启动这个 Flask RAG 示例第 1 步安装依赖Python 3.11pip install -r flask_react/requirements.txtflask_react/requirements.txt中锁定了Flask2.2.3、llama-index0.6.13、pypdf3.9.0等版本。第 2 步配置 API Keyflask_react/index_server.py第 5 行预留了OPENAI_API_KEY占位符作者注明仅限本地测试生产环境请改用环境变量。第 3 步一键启动三个服务sh flask_react/launch_app.shflask_react/launch_app.sh会依次拉起索引服务5602、Flask API5601和 React 前端3000其中sleep 60是为了等待索引首次加载完成。Docker 方式每个示例都自带Dockerfileflask_react/Dockerfile基于 python3.11nodejs16 镜像docker build后运行时加-p 5601:5601 -p 3000:3000即可访问。React 前端的可视化效果flask_react/react_frontend.png是 React 前端运行效果左侧上传文件并展示My Documents文档列表右侧输入问题后同时显示Query Response回答与Response Sources引用来源含相似度与起止位置——这正是 3 个接口的可视化组合。常见坑与注意事项400 错误/query忘带text参数或/uploadFile没用 form-data 格式提交file字段索引不更新索引持久化在flask_react/saved_index/vector_store.json、docstore.json、index_store.json想从零开始需删除该目录端口冲突本机已有服务占用 5601/5602/3000 时需先释放文件命名上传文件会先经过secure_filename清洗特殊字符文件名可能被改写这套 Flask API 示例代码量极小但五脏俱全参数校验、错误处理、并发保护、持久化、接口文档式响应都有体现非常适合作为从llama_index 脚本走向llama_index 服务化的第一课。输出文章【免费下载链接】llama_index_starter_packThis repository provides very basic flask, streamlit, and docker examples for the llama_index (fka gpt_index) package项目地址: https://gitcode.com/gh_mirrors/ll/llama_index_starter_pack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考