My LLM Inventory Task

基于GenAI的库存管理系统

项目概述

该项目实现了一个两层库存管理系统，其特征是一个核心库存Web服务和一个模型控制平面（MCP）服务器。MCP服务器利用Generative AI（特别是Google Gemini）解释库存操作的自然语言查询，将其转换为库存Web服务的结构化API调用。

该解决方案演示了API设计、微服务交互以及大型语言模型（LLM）的集成，以实现直观的用户界面。

项目结构

存储库组织如下：

.
├── inventory-service/
│   └── main.py              # Inventory Web Service implementation
├── mcp-server/
│   └── main.py              # Model Control Plane (MCP) Server implementation
|__ results_image            # Added a folder for screenshots of demo on local machine
├── .gitignore               # Specifies intentionally untracked files to ignore by Git
└── README.md                # This documentation file

FastAPI自动为这两种服务生成OpenAPI规范，可在/OpenAPI.json上访问（例如。，http://localhost:8000/openapi.json库存服务）。交互式文档（Swagger UI）可在/docs（例如。，http://localhost:8000/docs).

安装说明 按照以下步骤在本地计算机上设置和运行项目（提供了macOS说明）。

先决条件

1. Python 3.9+
2. Homebrew（建议在macOS上安装Python）
3. Git

1.克隆存储库

首先，将此GitHub存储库克隆到您的本地计算机：

git clone https://github.com/[YOUR_GITHUB_USERNAME]/[YOUR_REPO_NAME].git
cd [YOUR_REPO_NAME] # e.g., cd my-llm-inventory-task

2.Python环境设置

强烈建议使用Python虚拟环境来管理依赖关系。

# Navigate to the project root directory
cd ~/Documents/InternshipTask # Or wherever you cloned the repo

# Create a virtual environment
python3 -m venv venv

# Activate the virtual environment
# IMPORTANT: You must run this command in each new terminal session you open for this project.
source venv/bin/activate

3.安装依赖项

激活虚拟环境后，安装所需的Python包

pip install fastapi uvicorn pydantic httpx

4.获取并配置Gemini API密钥

MCP服务器需要Google Gemini API密钥才能与Generative AI模型交互。

1. 获取API密钥：

• 前往谷歌AI工作室。

• 使用您的Google帐户登录。

- 创建一个新的API密钥并立即复制它。

1. 设置为环境变量：

• 打开您的shell配置文件（例如，.zshrc表示zsh，.bash_profile或.bashrc表示bash）：

nano ~/.zshrc # Or ~/.bash_profile

• 将以下行添加到文件的最后，用复制的密钥替换YOUR_ACTUAL_GENINI_API_KEY_HERE：

  export GEMINI_API_KEY="YOUR_ACTUAL_GEMINI_API_KEY_HERE"

• 保存并退出nano（Ctrl+O或Ctrl+X）
• 将更改应用于当前终端：

source ~/.zshrc # Or ~/.bash_profile

• 至关重要的是，打开一个全新的终端窗口/选项卡
• 验证密钥是否设置在新终端中：（应显示API密钥）

    echo $GEMINI_API_KEY

运行服务

这两个服务必须在单独的终端窗口/选项卡中同时运行。

1.运行库存Web服务

• 打开一个新的终端窗口/选项卡并激活您的虚拟环境：

source venv/bin/activate

• 导航到库存服务目录：

cd inventory-service

• 启动服务：让终端保持运行

uvicorn main:app --host 0.0.0.0 --port 8000 --reload

2.运行模型控制平面（MCP）服务器

• 打开另一个新的终端窗口/选项卡。

• 激活您的虚拟环境：

  source venv/bin/activate

• 导航到mcp服务器目录：

  cd mcp-server

• 启动服务：

  uvicorn main:app --host 0.0.0.0 --port 8001 --reload

API终点和测试

您可以在第三个终端窗口（venv已激活）中使用curl命令或通过web浏览器中的交互式Swagger UI测试API。

库存Web服务(http://localhost:8000) 访问Swagger用户界面：http://localhost:8000/docs

GET/库存 检索T恤和裤子的当前库存水平。

curl -X GET "http://localhost:8000/inventory" \
     -H "accept: application/json"

POST/库存 修改库存中特定物品（T恤或裤子）的计数。

• 出售5件t恤：

curl -X POST "http://localhost:8000/inventory" \
     -H "accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{"item": "tshirts", "change": -5}'

• 添加10条裤子：

curl -X POST "http://localhost:8000/inventory" \
     -H "accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{"item": "pants", "change": 10}'

• 测试无效项目

curl -X POST "http://localhost:8000/inventory" \
     -H "accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{"item": "socks", "change": 1}'

• 测试将库存降至零以下（预期误差）：

curl -X POST "http://localhost:8000/inventory" \
     -H "accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{"item": "tshirts", "change": -100}'

模型控制平面（MCP）服务器(http://localhost:8001) 访问Swagger用户界面：http://localhost:8001/docs

POST/process_query 处理自然语言查询，使用GenAI对其进行解释，并与库存服务进行交互。

• 获取当前库存：

  curl -X POST "http://localhost:8001/process_query" \
     -H "accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{"query": "How many pants and shirts do I have?"}'

• 出售2件t恤：

  curl -X POST "http://localhost:8001/process_query" \
     -H "accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{"query": "I sold two t-shirts"}'

• 添加7条裤子

  curl -X POST "http://localhost:8001/process_query" \
     -H "accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{"query": "Add 7 pants to the stock"}'

• 检查特定商品的库存：

curl -X POST "http://localhost:8001/process_query" \
     -H "accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{"query": "What is the current stock of tshirts?"}'

• 测试不受支持的查询（预期错误）：

curl -X POST "http://localhost:8001/process_query" \
     -H "accept: application/json" \
     -H "Content-Type: application/json" \
     -d '{"query": "I want to buy a spaceship."}'

输出屏幕截图

下面附带的屏幕截图显示了在本地主机上代码的简要执行

1.库存Web服务

2.MCP服务器

在演示中执行卷曲操作后，t恤数量：9件，裤子数量：25条

设计选择和推理

• 为什么选择Python和FastAPI？

- FastAPI的高性能：FastAPI建立在用于web的Starlette和用于数据的Pydantic之上，实现了与Node.js和Go相当的高性能。这非常适合高吞吐量API服务。

- 易用性和快速开发：FastAPI提供了一种现代、直观和开发人员友好的体验，只需最少的样板文件，即可加速API的开发。

- 自动生成OpenAPI/Swagger UI：其功能是自动生成交互式API文档（Swagger UI-at/docs）和机器可读的OpenAPI规范（/OpenAPI.json）。这使得API的理解、测试以及人工开发人员和其他服务的集成更加容易。

- Pydantic的强类型提示：Pydantic模型用于数据验证和序列化/反序列化，其中包括强数据处理、显式API协定和较少的运行时错误。

- 异步功能：FastAPI原生支持async/await，这对于高效地进行I/O绑定操作至关重要，例如对Gemini LLM或Inventory Service等外部服务的非阻塞HTTP请求。

• 为什么选择Google Gemini API？

- 强大的自然语言理解能力：Gemini擅长解释复杂的自然语言查询并从中提取结构化信息。

- 结构化输出强制（responseSchema）：使用的一个关键功能是Gemini API generationConfig中的responseSchem功能。这允许MCP服务器明确请求LLM以预定义的JSON格式返回其解释（例如，指定操作、项目、更改）。这对于将非结构化用户查询可靠地转换为可操作的程序化命令至关重要。

- 意图识别性能：Gemini 2.0 Flash为这项特定的意图识别和参数提取任务提供了速度和能力的良好平衡，使其适用于实时API交互。

• 利用OpenAPI（FastAPI的自动文档）：

- FastAPI通过OpenAPI规范提供了全面的API文档。 - /docs端点提供了交互式Swagger UI，使开发人员能够直观地浏览所有端点，理解请求/响应模式，甚至可以直接从浏览器执行API调用。 - /openapi.json端点提供了API的机器可读json表示。这是一个正式的合同，使自动化工具（如代码生成器、API网关，甚至其他微服务）能够理解API并与之交互，而无需手动解析。这显著提高了可发现性和集成效率。

• 面向对象编程（OOP）概念：

- 应用程序对象：app=FastAPI（…）实例充当表示web应用程序的中心对象，封装其路由、中间件和配置。 - Pydantic模型（BaseModel）：InventoryResponse、InventoryUpdateRequest、NaturalLanguageQuery和MCPResponse等类是OOP的直接应用。它们定义了具有类型提示的清晰、可重用的数据结构，充当API请求和响应主体的架构。这通过将数据定义与业务逻辑明确分离来促进数据完整性、可读性和可维护性。 - 模块化函数：每个API端点（get_inventory、update_inventory和process_natural_language_query）和辅助函数（call_gemini_lilm）都封装在自己的函数中，每个端点负责特定的任务。这种模块化增强了代码组织、可重用性和可测试性。

• LLM互动的快速设计：

- mcp-server/main.py中的llm_prompt经过精心设计，以指导llm的行为。 - Clear Role Assignment：提示明确地“告诉”LLM其功能：“一个智能助手，将自然语言库存请求转换为结构化JSON命令。” - 具体指令和约束：它定义了确切的字段（操作、项目、更改、推理）及其允许的值（例如，操作为“GET”或“POST”，项目为“tshirts”或“pants”），确保LLM的输出是可预测和可解析的。 - 少镜头示例：提供多个用户查询的具体示例及其相应的所需JSON响应对于“少镜头学习”至关重要。这大大提高了LLM准确解释新的、看不见的查询并一致生成正确结构化输出的能力，即使措辞有变。 - JSON模式实施：Gemini API调用中的responseSchema通过编程实施所需的JSON结构来加强提示的指令，使LLM的输出对于下游处理非常可靠。

• MCP服务器逻辑流程：

- 输入接收：MCP服务器通过其/process_query端点从客户端接收自然语言查询。 - LLM解释：它构造了一个详细的提示，包含用户的查询，并将其发送给call_gemini_lilm辅助函数。 - 动作确定：call_gemini_lilm函数与Google gemini API交互，后者返回一个结构化JSON对象（感谢responseSchema），其中包含预期操作（GET/POST）、项目、更改和推理。 - 库存服务交互：基于LLM的解释操作和参数，MCP服务器然后向本地库存Web服务发出精确的HTTP请求（带有相关项目和更改金额的GET/库存或POST/库存）。 - 响应生成：最后，MCP服务器将Inventory Service的结果（或适当的错误消息）编译为MCPResponse对象，向原始客户端提供明确的消息和investory_state。 - 稳健的错误处理：全面的试接受块贯穿始终，以妥善处理潜在问题，如网络连接问题、Gemini API返回的错误、格式错误的LLM响应或库存服务错误。

已知限制

这个项目是一个功能原型，有一定的局限性：

• 内存数据存储：库存数据存储在内存中，每当重新启动库存服务时，库存数据将重置为其初始状态（T恤：20，裤子：15）。对于生产，需要一个持久数据库（例如PostgreSQL、MongoDB、SQLite）。
• 有限物品支持：根据任务要求，系统目前仅支持“T恤”和“裤子”作为库存物品。扩展此功能将涉及更新库存服务和LLM的提示/模式。
• LLM解释可变性：虽然快速工程有帮助，但LLM偶尔会误解高度模糊、非常复杂或超出范围的自然语言查询。强大的生产系统可能需要更复杂的回退机制或人工在环验证。
• 基本错误处理：错误处理是功能性的，但可以针对生产环境进行增强（例如，更具体的错误代码、自定义错误响应、全面的日志记录和监控）。
• 无身份验证/授权：API均未实施任何安全措施（身份验证或授权）。对于真实世界的应用程序，安全访问控制至关重要。
• 无动态API发现：MCP服务器使用资源清册服务的URL和端点结构进行硬编码。在更复杂的微服务架构中，可以考虑动态服务发现或在运行时读取Inventory service的OpenAPI规范，以获得更大的灵活性。