快速入门

首先，如果您尚未安装，请先安装 Homebrew，然后执行以下命令：

brew tap vllora/vllora
brew install vllora

启动 vLLora：

vllora

服务器将在 http://localhost:9090 启动，UI 界面则可在 http://localhost:9091 访问。

vLLora 使用与 OpenAI 兼容的聊天完成 API，因此当您的 AI 代理通过 vLLora 发起调用时，它会自动收集每次交互的追踪信息和调试数据。

测试：发送您的第一个请求

1. 配置 API 密钥：访问 http://localhost:9091，通过 UI 配置您的 AI 提供商 API 密钥。
2. 发起请求，查看调试效果：

curl http://localhost:9090/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "法国的首都是哪里？"}]
  }'

Rust 流式示例（与 OpenAI 兼容）

在 llm/examples/openai_stream_basic/src/main.rs 中，您可以找到一个极简的 Rust 示例，该示例：

• 使用 CreateChatCompletionRequestArgs 构建一个 OpenAI 风格的请求，其中：
  • model("gpt-4.1-mini")
  • 一条 系统消息：“您是一位乐于助人的助手。”
  • 一条 用户消息：“请将数字 1 到 20 分别以单独的一行输出。”
• 构建 VlloraLLMClient 并通过以下方式配置凭据：

export VLLORA_OPENAI_API_KEY="your-openai-compatible-key"

在示例中，客户端大致按如下方式创建：

let client = VlloraLLMClient::new()
    .with_credentials(Credentials::ApiKey(ApiKeyCredentials {
        api_key: std::env::var("VLLORA_OPENAI_API_KEY")
            .expect("必须设置 VLLORA_OPENAI_API_KEY")
    }));

随后，它使用原始的 OpenAI 风格请求进行流式处理：

let mut stream = client
    .completions()
    .create_stream(openai_req)
    .await?;

while let Some(chunk) = stream.next().await {
    let chunk = chunk?;
    for choice in chunk.choices {
        if let Some(delta) = choice.delta.content {
            print!("{delta}");
        }
    }
}

这将逐段打印流式响应内容（本例中为数字 1 至 20）到标准输出。

功能特性

实时追踪 - 实时监控 AI 代理的交互过程，包括调用、工具交互及代理工作流的可观测性。让您精确了解代理在实时中的操作。

MCP 支持 - 完全支持模型上下文协议（MCP）服务器，可通过 HTTP 和 SSE 连接 MCP 服务器，实现与外部工具的无缝集成。

开发

开始开发的步骤如下：

1. 克隆仓库：

git clone https://github.com/vllora/vllora.git
cd vLLora
cargo build --release

编译后的二进制文件将位于 target/release/vlora。

2. 运行测试：

cargo test

贡献

我们欢迎各位贡献！请查阅我们的 贡献指南，了解以下内容：

• 如何提交问题
• 如何提交拉取请求
• 代码风格规范
• 开发流程
• 测试要求

您有 bug 报告或功能需求吗？请查看我们的 问题列表，了解当前正在进行的工作或提交新问题。

路线图

请查看我们的 路线图，了解接下来的计划！

许可证

vLLora 是基于 fair-code 的项目，采用 Elastic License 2.0 (ELv2) 协议进行分发。

内部包 llm 则采用 Apache License 2.0 协议分发。

vLLora 包含 Distri 作为可选组件，用于 AI 代理功能。Distri 基于 Elastic License 2.0 (ELv2) 协议分发，并在运行时单独下载。Distri 是由 DistriHub 维护的一个独立项目。

• 源码开放：vLLora 源代码始终公开可见。
• 可自托管：您可以在任何需要的地方部署 vLLora。
• 可扩展：添加您自己的提供商、工具、MCP 服务器以及自定义功能。

如需企业许可证，请联系我们的邮箱：hello@vllora.dev。

有关许可模式的更多信息，请参阅文档。

vLLora 快速上手指南

vLLora 是一款轻量级、实时的 AI Agent 调试工具。它支持 LangChain、Google ADK、OpenAI 等主流框架，能够自动收集交互轨迹（Traces）并实时分析，帮助开发者即时优化 Agent 工作流。

环境准备

• 操作系统：macOS 或 Linux（推荐通过 Homebrew 安装）。
• 前置依赖：
  • Homebrew：包管理工具（macOS/Linux）。
  • 若未安装 Homebrew，请先运行官方安装脚本。
• 网络要求：需确保能访问 localhost:9090 和 localhost:9091 端口。

注意：目前官方主要提供 Homebrew 安装方式。国内用户若遇到 Homebrew 下载缓慢问题，可配置国内镜像源（如中科大或清华源）加速 brew 本身的操作，但 vllora tap 源仍需从 GitHub 拉取。

安装步骤

1. 添加 vLLora 源并安装： 在终端中依次执行以下命令：

   brew tap vllora/vllora
   brew install vllora
   

2. 验证安装： 安装完成后，输入 vllora --version（或直接运行启动命令）确认工具可用。

基本使用

1. 启动服务

在终端运行以下命令启动 vLLora：

vllora

启动成功后，你将看到如下服务地址：

• API 服务端点：http://localhost:9090（用于接收 AI 请求）
• 可视化调试界面：http://localhost:9091（用于查看轨迹和配置）

2. 配置 API Key

1. 打开浏览器访问 http://localhost:9091。
2. 在 UI 界面中配置你的 AI 提供商 API Key（如 OpenAI Key），以便 vLLora 代理转发请求。

3. 发送测试请求

vLLora 兼容 OpenAI 的 Chat Completions API。你可以直接将原本发往 OpenAI 的请求地址改为 http://localhost:9090/v1/chat/completions 即可自动开启调试追踪。

使用 curl 发送第一条测试消息：

curl http://localhost:9090/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "What is the capital of France?"}]
  }'

发送后，返回浏览器刷新 http://localhost:9091 页面，即可看到该次交互的完整实时轨迹（Traces）、耗时及内容详情。

4. 进阶：Rust 流式调用示例

如果你使用 Rust 开发，vLLora 提供了兼容 OpenAI 风格的流式客户端。

前置设置： 导出环境变量配置密钥：

export VLLORA_OPENAI_API_KEY="your-openai-compatible-key"

代码示例： 构建请求并流式输出结果：

let client = VlloraLLMClient::new()
    .with_credentials(Credentials::ApiKey(ApiKeyCredentials {
        api_key: std::env::var("VLLORA_OPENAI_API_KEY")
            .expect("VLLORA_OPENAI_API_KEY must be set")
    }));

let mut stream = client
    .completions()
    .create_stream(openai_req)
    .await?;

while let Some(chunk) = stream.next().await {
    let chunk = chunk?;
    for choice in chunk.choices {
        if let Some(delta) = choice.delta.content {
            print!("{delta}");
        }
    }
}

运行上述代码后，终端将逐字打印流式响应内容，同时 vLLora 后台会自动记录完整的调试信息。