跳至主要内容

Rivet CLI - serve 命令

使用本地服务器运行Rivet项目。

快速入门​

# Start server with default settings
npx @ironclad/rivet-cli serve

# Start server on custom port
npx @ironclad/rivet-cli serve --port 8080

# Start server in development mode
npx @ironclad/rivet-cli serve --dev

描述​

serve 命令启动一个本地HTTP服务器，用于托管您的Rivet项目，允许您通过HTTP请求执行图形。这在以下情况下特别有用：

  • 在类似生产环境中测试图形
  • 将Rivet图表集成到其他应用程序中
  • 从脚本或自动化工具运行图形
  • 图形化实现的开发与调试

使用方法​

基本用法将在当前目录中提供项目文件服务，使用默认端口3000：

npx @ironclad/rivet-cli serve

你也可以指定不同的项目文件或端口：

npx @ironclad/rivet-cli serve my-project.rivet-project --port 8080

服务器运行后，您可以向服务器发送POST请求来运行图形。

输入项​

图表的输入通过HTTP请求的请求体提供。请求体应是一个包含输入值的JSON对象。

输入值应作为数据值提供，字符串、数字和布尔值等简单类型除外。

例如，对于一个有两个输入的图表，input1（字符串）和input2（对象），请求体应如下所示：

{
  "input1": "Hello, World!",
  "input2": {
    "type": "object",
    "value": {
      "key1": "value1",
      "key2": 42
    }
  }
}

输出​

服务器将返回一个包含图表输出值的JSON对象。图表中的每个Graph Output节点将对应输出JSON对象中的一个键。

每个属性的值将是一个Data Value对象，包含一个type属性和一个value属性。

例如，如果一个图表有两个Graph Output节点，output1（字符串类型）和output2（数字类型），输出的JSON对象将如下所示：

{
  "output1": {
    "type": "string",
    "value": "Hello, World!"
  },
  "output2": {
    "type": "number",
    "value": 42
  }
}

端点​

POST /​

运行项目文件中的主图。请求正文应包含上述描述的输入值。

输出一个包含图表输出值的JSON对象。

POST/:graphId​

只有在使用--allow-specifying-graph-id标志时才会启用此功能。此端点运行项目文件中的特定图形。

请求正文应包含如上所述的输入值。

输出一个包含图表输出值的JSON对象。

选项​

服务器配置​

  • --port : 运行服务器的端口号。默认为3000。
  • --dev: 以开发模式运行服务器，该模式会在每次请求时重新读取项目文件。适用于开发环境。

图表选择​

  • --graph : 要运行的图名称或ID。如果未提供，将运行主图。如果没有主图，将返回错误。
  • --allow-specifying-graph-id: 允许在URL路径中指定图形ID。默认情况下此功能是禁用的。

OpenAI 配置​

  • --openai-api-key: 用于Chat节点的OpenAI API密钥。如果项目使用OpenAI功能或需要API密钥，则必须提供。如果省略，将使用环境变量OPENAI_API_KEY。
  • --openai-endpoint: 用于Chat节点的OpenAI API端点。默认为https://api.openai.com/v1/chat/completions。如果省略，将使用环境变量OPENAI_ENDPOINT。
  • --openai-organization: 要使用的OpenAI组织ID。如果省略，将使用环境变量OPENAI_ORGANIZATION。

监控​

  • --expose-cost: 将图形运行成本作为属性暴露在JSON响应对象中。默认情况下禁用。

示例​

运行一个简单的Graph​

请求：

curl -X POST http://localhost:3000 -H "Content-Type: application/json" -d '{
  "name": "Alice",
  "age": 30
}'

响应:

{
  "greeting": {
    "type": "string",
    "value": "Hello, Alice!"
  },
  "canVote": {
    "type": "boolean",
    "value": true
  }
}

安全注意事项​

  • 该服务器仅用于开发和测试目的
  • 服务器未提供任何身份验证，因此在没有额外安全措施的情况下不应将其暴露在互联网上。
  • 如果暴露在互联网环境中，建议在反向代理后运行，以增加SSL、速率限制和身份验证等安全功能。
  • 对于敏感配置（如API密钥）请使用环境变量

流式模式​

rivet serve 根据您将要集成的应用程序类型，提供了两种不同的流式传输模式。无论哪种情况，服务器都会以SSE（服务器发送事件）格式流式传输事件，这是一种从服务器向客户端流式传输数据的简单高效方式。

Rivet事件流模式​

默认情况下，当提供--stream参数时，服务器将以Rivet Events格式流式传输事件。该格式专为理解Rivet Events系统的应用程序设计，能够正确处理这些事件。

以下是Rivet Events格式的流式响应示例：

event: nodeStart
data: {
    "inputs": {
        "prompt": {
            "type": "string",
            "value": "h4110"
        }
    },
    "nodeId": "vzC9lcEyXZ2Q1-cCaG0v4",
    "nodeTitle": "Chat",
    "type": "nodeStart"
}

event: partialOutput
data: {
    "delta": "",
    "nodeId": "vzC9lcEyXZ2Q1-cCaG0v4",
    "nodeTitle": "Chat",
    "type": "partialOutput"
}

event: partialOutput
data: {
    "delta": "It seems like you entered \"h",
    "nodeId": "vzC9lcEyXZ2Q1-cCaG0v4",
    "nodeTitle": "Chat",
    "type": "partialOutput"
}

event: partialOutput
data: {
    "delta": "4110.\" Could",
    "nodeId": "vzC9lcEyXZ2Q1-cCaG0v4",
    "nodeTitle": "Chat",
    "type": "partialOutput"
}

event: partialOutput
data: {
    "delta": " you please provide more context or clarify what you would like to know or",
    "nodeId": "vzC9lcEyXZ2Q1-cCaG0v4",
    "nodeTitle": "Chat",
    "type": "partialOutput"
}

event: partialOutput
data: {
    "delta": " discuss regarding that term?",
    "nodeId": "vzC9lcEyXZ2Q1-cCaG0v4",
    "nodeTitle": "Chat",
    "type": "partialOutput"
}

event: nodeFinish
data: {
    "nodeId": "vzC9lcEyXZ2Q1-cCaG0v4",
    "nodeTitle": "Chat",
    "outputs": {
        "__hidden_token_count": {
            "type": "number",
            "value": 68
        },
        "all-messages": {
            "type": "chat-message[]",
            "value": [
                {
                    "message": "h4110",
                    "type": "user"
                },
                {
                    "message": "It seems like you entered \"h4110.\" Could you please provide more context or clarify what you would like to know or discuss regarding that term?",
                    "type": "assistant"
                }
            ]
        },
        "cost": {
            "type": "number",
            "value": 2.475e-05
        },
        "duration": {
            "type": "number",
            "value": 846
        },
        "in-messages": {
            "type": "chat-message[]",
            "value": [
                {
                    "message": "h4110",
                    "type": "user"
                }
            ]
        },
        "requestTokens": {
            "type": "number",
            "value": 10
        },
        "response": {
            "type": "string",
            "value": "It seems like you entered \"h4110.\" Could you please provide more context or clarify what you would like to know or discuss regarding that term?"
        },
        "responseTokens": {
            "type": "number",
            "value": 58
        },
        "usage": {
            "type": "object",
            "value": {
                "completion_cost": 2.325e-05,
                "completion_tokens": 31,
                "completion_tokens_details": {
                    "accepted_prediction_tokens": 0,
                    "audio_tokens": 0,
                    "reasoning_tokens": 0,
                    "rejected_prediction_tokens": 0
                },
                "prompt_cost": 1.4999999999999998e-06,
                "prompt_tokens": 10,
                "prompt_tokens_details": {
                    "audio_tokens": 0,
                    "cached_tokens": 0
                },
                "total_cost": 2.475e-05,
                "total_tokens": 41
            }
        }
    },
    "type": "nodeFinish"
}

您可以看到服务器正在流式传输诸如nodeStart、partialOutputs和nodeFinish这样的事件。每个事件的数据都是一个包含该事件相关信息的JSON对象。

单节点流模式​

如果设置--stream=NodeId或--stream=NodeTitle，服务器将仅流式传输指定节点的事件。如果您只对图中特定节点的事件感兴趣，这将非常有用。

文本流模式​

如果您正在与一个只接受文本响应的简单应用程序集成，可以同时设置--stream-node=NodeId / --stream-node=NodeTitle 和 --stream参数。

这将导致流式传输看起来像以下内容：

data: ""

data: "It seems like you entered \"h"

data: "4110,\" which could refer"

data: " to a variety of things depending on the context."

data: " It could be a model number, a"

data: " code, or something else."

data: " Could you please provide more details or clarify what you"

data: " are referring to?"

data: " This will help me assist you better!"

您可以看到每个data事件都包含来自节点的响应文本增量。

在此模式下，您应该仅指定Chat节点，因为其他节点可能不具备支持此功能的部分输出。