煎蛋 - Gendial

简体中文

English

简体中文

English

Appearance

OpenAI 兼容 API 调用 ​

煎蛋平台的智能体可以通过OpenAI 兼容 API 的方式被其他软件或者OpenAI 库直接调用，你可以很容易的把创建的煎蛋智能体接入类似Chatbox或者cherryStudio这样的开源软件中。你也可以通过API的方式把煎蛋智能体的能力接入已有的业务系统中。

以下是对应的OpenAI API 关键参数：

基准URL（BaseURL） ​

https://gendial.cn/api/v1

model 参数 ​

Model参数为智能体的GUID，可以在智能体浏览器里查到：

alt text

apiKey 参数 ​

apiKey 为 智能体的API密钥：

alt text

其他OpenAI 参数 ​

智能体 API 支持其他OpenAI API 规定的参数，其中常用的参数包括：

  • max_tokens： 模型回复最大长度（单位 token），这个长度还受模型的上下文长度限制。

  • stream：是否需要流式输出，这个设置要配合智能体的输出节点的 流式输出 输出设置才能正常工作。如果智能体不支持流式输出，则即使API参数里设置了 steam 为 true， 也无法实现流式输出。

  • temperature： 采样温度。控制了生成文本时对每个候选词的概率分布进行平滑的程度。取值范围为 [0, 1]。当取值为 0 时模型仅考虑对数概率最大的一个 token。 较高的值（如 0.8）会使输出更加随机，而较低的值（如 0.2）会使输出更加集中确定。通常建议仅调整 temperature 或 top_p 其中之一，不建议两者都修改。

  • top_p： 核采样概率阈值。模型会考虑概率质量在 top_p 内的 token 结果。取值范围为 [0, 1]。当取值为 0 时模型仅考虑对数概率最大的一个 token。 如 0.1 意味着只考虑概率质量最高的前 10% 的 token，取值越大生成的随机性越高，取值越低生成的确定性越高。通常建议仅调整 temperature 或 top_p 其中之一，不建议两者都修改。

⚠️ 注意：不支持tools参数。

标准OpenAI请求示例 ​

以下为使用curl命令的请求示例

curl https://gendial.cn/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer API_KEY \
  -d '{
    "model": AGENT_GUID,
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": "Hello!"
        }
    ]
  }'

煎蛋平台扩展参数 ​

除了标准的OpenAI 参数之外，API 调用还支持以下的参数，用以支持平台复杂的智能体功能。

memoryId 参数 ​

memoryId 是服务端用来记录用户与智能体的当前对话历史，和当前智能体运行的节点状态的信息。每次API调用时，可以传递memoryId参数，用来标识当前对话的历史。智能体每次回复都会返回memoryId字段，供客户端复用。

与OpenAI的API规范结合后，可以有以下几种情况：

  1. 不使用memoryId：这种模式是标准的OpenAI规范调用方式，客户端需要自行组织对话历史，并通过messages字段发送给智能体。每一次调用都会被智能体认为是一次全新的对话，都从流程的开始节点执行，每次智能体都会回复新的memoryId。此种模式适合简单的，不涉及到循环工作流的大模型问答。

  2. 使用memoryId：在这种情况下，客户端第一次与智能体对话不发送memoryId，等待智能体返回memoryId之后，记录下当前memoryId。在后续的对话中传递这个memoryId，这样智能体就能够知道对话历史和运行的当前节点状态。如果想要开启新的对话，只要不传递memoryId即可。

在使用memoryId的情况下，客户端无需自行组织对话历史。也就是说 messages 字段只需要一个用户消息，智能体会从服务端会自行获取保存的对话历史进行处理。智能体获取的对话历史数目可以在智能体设置里设定。

在与复杂的，包含循环工作流的智能体对话时，需要正确的使用memoryId参数，否则每次对话都会从头开始，导致智能体无法正常工作。

imageUrl 参数 ​

在智能体 / 大模型支持图片多模态能力的情况下，可以通过API传递 imageUrl 参数。这个imageUrl参数和OpenAI 规范里的 image_url一致，既可以用imageUrl 进行传递也可以在messages里用 image_url传递

fileUrl 参数 ​

在智能体支持文件的多模态能力的情况下，可以通过API传递 fileUrl 参数。这个url必须是平台能够访问到的地址。传递这个参数之后，智能体就可以通过系统变量 {{sys.fileUrl}} 来引用，用于代码节点等进行下载和读取。

originalFileName 参数 ​

在智能体支持文件的多模态能力的情况下，可以通过API传递 originalFileName 参数。这个参数需要和前面的 fileUrl 参数匹配使用。递这个参数之后，智能体就可以通过系统变量 {{sys.fileName}} 来引用。

variables 参数 ​

除了标准的OpenAI api，煎蛋智能体 API 还可以传递 variables 参数。这个参数是用来设置智能体运行时的变量值，这样就可以通过 API 来控制智能体的工作流和具体行为。

variables的格式为字符串字典对象:

{"key1": "value1","key2": "value2",..,"keyN": "valueN"}

煎蛋平台扩展的API调用示例 ​

curl https://gendial.cn/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer API_KEY \
  -d '{
    "model": AGENT_GUID,
    "memoryId": YOUR_MEMORY_ID,    
    "messages": [
        {
            "role": "user",
            "content": "Hello!"
        }
    ],
    "fileUrl": YOUR_FILE_URL,
    "originalFileName": FILE_NAME,
    "variables": {
        "var1": "value1",
        "var2": "value2",
    }
  }'

Last updated: