应用文档

作者: 新篇章 | 来源:发表于2023-07-30 21:34 被阅读0次

钉钉和企业微信内部应用开发
2017.9.29
Markdown 入门
NSLocalizedString
微信分享时提示“未验证应用”
2017-9-29学习总结
Kotlin学习资源大收集
Kotlin资源合集(转)
Electron创建应用以及打包exe
Peewee中文文档

API 应用文档

该指南为您提供详细说明，帮助您更好地配置API的输入和输出应用。

输入应用

输入应用是在发送API请求前指定数据内容的过程。它由两部分组成：参数，消息，附件。

1. 参数 (Parameters)

参数是用于配置和自定义的关键元素，这份文档详细描述了各种参数类型和其在前端的配置方式。

1. 数值型 (Numerical)

数值型参数用于表示一个范围内的数值。

属性	描述	示例
参数名	用于识别参数的名称	"temperature"
最小值	参数可以接受的最小数值	0
最大值	参数可以接受的最大数值	1
步长	数值之间的增量	0.1
值 (Value)	如果没有指定值，则使用的数值	0.8
描述	参数的简短描述	"设置温度值"

前端显示: 通常为滑块或数字输入框。

用户可以在最大值和最小值之间选择一个值。
滑块或数字输入框应该按照指定的步长增加或减少。

2. 字符固定型 (Fixed String)

字符固定型参数具有预设的值，并不能更改。

属性	描述	示例
参数名	用于识别参数的名称	"model"
值 (Value)	预设的字符值	"gpt-3.5-turbo-16k"
描述	参数的简短描述	"选择模型名称"

前端显示: 文本框或标签。

用户不能修改这个值。

3. 选择型 (Option)

选择型参数允许用户从预定的几个选项中选择。

属性	描述	示例
参数名	用于识别参数的名称	"colorScheme"
多选 (allowm)	是否允许多选	Fales
选项 (Options)	可以选择的预定值列表	["Red", "Green", "Blue"]
描述	参数的简短描述	"选择颜色方案"

前端显示: 下拉菜单。

如果 allowm 为 true，则下拉菜单应允许多选。
如果 allowm 为 false，则用户只能选择一个选项。

4. 布尔型 (Boolean)

布尔型参数表示true或false值。

属性	描述	示例
参数名	用于识别参数的名称	"stream"
值 (Value)	布尔值，表示开或关	true
描述	参数的简短描述	"是否启用流模式"

前端显示: 开关按钮或复选框。

用户只能在 true 和 false 之间进行选择。

API 参数配置示例

以下是一个GPT对话的API参数的示例：

{
  "parameters": [
    {
      "name": "temperature",
      "type": "number",
      "value": 0.8,
      "min": 0.2,
      "max": 1,
      "step": 0.1,
      "description": "控制AI输出的温度，数值越高输出内容越多样，越低则越集中。"
    },
    {
      "name": "model",
      "type": "Fixed String",
      "value": "gpt-3.5-turbo-16k",
      "description": "指定使用的AI模型版本。"
    },
    {
      "name": "stream",
      "type": "boolean",
      "value": true,
      "description": "决定是否使用流式处理，提供实时的AI响应。"
    }
  ]
}

根据这个参数拼出来的输入参数Json如下：

{
  "parameters": {
    "temperature": 0.8,
    "model": "gpt-3.5-turbo-16k",
    "boolean": true
  }
}

以下是一个DALLE的案例：

{
  "parameters": [
    {
      "name": "n",
      "type": "integer",
      "value": 1,
      "min": 1,
      "max": 5,
      "description": "生成图像的数量，取值范围是1到5。"
    },
    {
      "name": "size",
      "type": "Option",
      "allowm":false,
      "options": ["256x256", "512x512", "1024x1024"],
      "value": "1024x1024",
      "description": "生成图像的大小，可选值包括'256x256', '512x512', 和 '1024x1024'。"
    },
    {
      "name": "response_format",
      "type": "Fixed String",
      "value": "url",
      "description": "生成图像的返回格式，此参数固定为URL。"
    }
  ]
}

{
  "parameters": {
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }
}

以下是SD生成图片的案例

{
  "parameters": [
    {
      "name": "samples",
      "type": "number",
      "description": "您希望在响应中获取的图像数量",
      "value": 1,
      "min": 1,
      "max": 5,
      "step": 1
    },
    {
      "name": "width",
      "type": "number",
      "description": "输出图像的宽度",
      "value": 256,
      "min": 256,
      "max": 1024,
      "step": 256
    },
    {
      "name": "height",
      "type": "number",
      "description": "输出图像的高度",
      "value": 256,
      "min": 256,
      "max": 768,
      "step": 256
    },
    {
      "name": "prompt_strength",
      "type": "number",
      "description": "使用初始图像时的提示强度。1.0对应于初始图像中信息的完全破坏",
      "value": 0.5,
      "min": 0,
      "max": 1.0,
      "step": 0.1
    },
    {
      "name": "num_inference_steps",
      "type": "number",
      "description": "去噪步骤的数量",
      "value": 20,
      "min": 10,
      "max": 50,
      "step": 10
    },
    {
      "name": "safety_checker",
      "type": "Fixed String",
      "description": "图像合规检查",
      "value": "yes"
    }
  ]
}

{
    "parameters": {
        "samples": 1,
        "height": 256,
        "width": 256,  
        "prompt_strength":0.5,
        "num_inference_steps":20,  
        "safety_checker": "yes"
    }
}

以下是优化提示的json案例

{
  "parameters": [
    {
      "name": "targetModel",
      "type": "Option",
      "description": "此提示词将用于的目标模型。",
      "options": [
        "chatgpt",
        "gpt-4",
        "stablelm-tuned-alpha-7b",
        "claude",
        "claude-2",
        "cogenerate",
        "jinachat",
        "text-davinci-003",
        "dalle",
        "sd",
        "midjourney",
        "kandinsky",
        "lexica"
      ],
      "value": "chatgpt"
    },
    {
      "name": "features",
      "type": "Option",
      "allowm":true,
      "description": "为提示词优化启用的附加功能。它可以是单个功能或多个功能。",
      "options": [
        "preview",
        "no_spam",
        "shorten",
        "bypass_ethics",
        "same_language",
        "always_en",
        "high_quality",
        "redo_original_image",
        "variable_subs",
        "template_run"
      ],
      "value": ["preview", "no_spam"]
    },
    {
      "name": "iterations",
      "type": "number",
      "description": "用于提示词优化的迭代次数。更大的迭代次数将导致更好的优化，但需要更长的时间。",
      "min": 1,
      "max": 5,
      "step": 1,
      "value": 1
    },
    {
      "name": "timeout",
      "type": "Fixed String",
      "description": "仅在 /optimizeBatch 中使用。等待优化完成的最长服务器时间（以毫秒为单位）。如果优化花费的时间超过此时间，优化将被取消并且不会返回该特定结果。",
      "value": "60000"
    },
    {
      "name": "targetLanguage",
      "type": "Option",
      "allowm":false,
      "description": "指定优化提示词的语言代码。",
      "options": ["zh-CN", "en"],
      "value": "zh-CN"
    }
  ]
}

{
    "parameters": {
        "targetModel": "chatgpt",
        "features": ["preview", "no_spam"],
        "iterations": 1,  
        "iterations":0.5,
        "timeout":60000,  
        "targetLanguage": "zh-CN"
    }
}

2. 文本消息Context

context包括了历史消息、用户的消息

消息是请求体的关键组成部分，用于构建与助手之间的对话。这份文档详细描述了消息的结构及其应用方式。

1. 上下文消息 (`contextMessages`)

上下文消息表示之前的对话内容，为助手提供关于当前对话的背景。

属性	描述	示例
角色 (`role`)	消息的发送者，可以是系统、用户或助手	"system", "user", "assistant"
内容 (`content`)	消息的文本内容	"You are a helpful assistant."

前端:

"user", "assistant"：前端将上下文的消息以不同的角色进行传递
"system"：作为机器人的提示词进行传递

<img src="./API 应用文档.assets/image-20230730183908004.png" alt="image-20230730183908004" style="zoom:50%;" />

示例:

"contextMessages": [
    {"role": "user", "content": "Hello!"},
    {"role": "assistant", "content": "Thank you for the compliment!"}
]

2. 最新消息 (`latestMessage`)

最新消息表示当前对话中用户或助手的最新消息。

属性	描述	示例
角色 (`role`)	消息的发送者，通常是用户或助手	"user", "assistant"
内容 (`content`)	消息的文本内容	"Tell me more about the weather today."

前端显示:

通常显示在聊天界面的底部，表示最新的消息或请求。

示例:

"latestMessage": {
    "role": "user",
    "content": "Tell me more about the weather today."
}

3. 输入附件 (Attachments)

了解，以下是扩展的附件配置文档：

附件配置文档

1. 附件 (`attachments`)

附件允许用户上传文件或提供URL，使助手能够访问和参考。这些文件或链接可能是图片、文档、音频或其他支持的类型。

a. 图片 (`image`)

代表图片文件。常用于展示、分析或其他需要图片参考的场景。

属性	描述	示例
文件类型 (`fileType`)	指明文件的类型，此处为“image”	"image"
文件链接 (`fileURL`)	指向文件的完整URL，用于下载或访问文件	"https://yourdomain.com/path/to/file1.jpg"

b. 文档 (`doc`)

代表文档文件，例如Word、PDF等。常用于提供长篇内容或结构化的资料。

属性	描述	示例
文件类型 (`fileType`)	指明文件的类型，此处为“doc”	"doc"
文件链接 (`fileURL`)	指向文件的完整URL，用于下载或访问文件	"https://yourdomain.com/path/to/file2.doc"

c. 音频 (`audio`)

代表音频文件。可以是讲座、歌曲、录音等。

属性	描述	示例
文件类型 (`fileType`)	指明文件的类型，此处为“audio”	"audio"
文件链接 (`fileURL`)	指向音频的完整URL，用于播放或下载音频	"https://yourdomain.com/path/to/audiofile.mp3"

d. 网站URL (`webURL`)

代表一个网站的链接。可以是文章、在线工具或其他网页。

属性	描述	示例
文件类型 (`fileType`)	指明文件的类型，此处为“webURL”	"webURL"
文件链接 (`fileURL`)	指向网站的完整URL	"https://www.example.com"

前端应用:

图片: 上传图片后，先调用上传图片的接口，返回URL后，进行调用
文档: 上传文档后，调用文档上传接口后，返回地址,进行调用。
音频: 调用音频接口，用户录完后，上传音频，返回地址，进行调用
网站URL: 通常提供一个点击的链接，使用户能够在新窗口打开指定的网站。

示例:

"attachments": [
    {"fileType": "image", "fileURL": "https://yourdomain.com/path/to/file1.jpg"},
    {"fileType": "doc", "fileURL": "https://yourdomain.com/path/to/file2.doc"},
    {"fileType": "audio", "fileURL": "https://yourdomain.com/path/to/audiofile.mp3"},
    {"fileType": "webURL", "fileURL": "https://www.example.com"}
]

输出应用文档

当与后端交互时，前端应该根据以下的配置来处理输出，并对用户进行相应的提示和界面展示。

1. 正常响应

正常响应表示API请求被成功处理。它包含状态、代码、消息、助手的响应和可能的附件。

属性	描述	示例
状态 (`status`)	表示请求处理的结果	"success"
代码 (`code`)	HTTP响应码	200
消息 (`message`)	提供额外的关于请求处理的详细信息	"Processed successfully"
响应 (`responses`)	包含助手的回复消息	[{"role": "assistant", "content": "The weather today is sunny."}]
附件 (`attachments`)	包含可能的附件，格式与输入中的附件配置相同	[{"fileType": "image", "fileURL": "https://yourdomain.com/path/to/response_image.jpg"}]

前端响应要求:

状态为“success”时:
- 显示助手的响应消息。
- 如果有附件，提供链接或直接展示在界面上。
- 可以在某个界面角落显示消息内容（例如："Processed successfully"）。

示例：

{
  "status": "success",
  "code": 200,
  "message": "Processed successfully",
  "responses": [
    {"role": "assistant", "content": "The weather today is sunny with a high of 25°C."}
  ],
  "attachments": [
    {"fileType": "image", "fileURL": "https://yourdomain.com/path/to/response_image.jpg"}
  ]
}

2. 错误处理

错误处理表示当API遇到错误时的响应格式。

属性	描述	示例
状态 (`status`)	表示请求处理的结果	"error"
代码 (`code`)	HTTP错误响应码	400
消息 (`message`)	提供额外的关于错误的详细信息	"Invalid file type"
错误详情 (`errorDetails`)	提供具体的错误信息，帮助用户或开发者识别和修复问题	"The provided file type is not supported."

前端响应要求:

状态为“error”时:
- 显示明显的错误提示消息（例如：红色警告标签）。
- 给用户提供错误详情，帮助他们理解问题所在。
- 如果可能，提供建议的解决步骤或联系客服的链接。

示例：

{
  "status": "error",
  "code": 400,
  "message": "Invalid file type",
  "errorDetails": "The provided file type is not supported."
}

钉钉和企业微信内部应用开发
配置前的准备运营人员创建相关企业内部应用。重要文档钉钉内部应用文档。企业微信内部应用文档。开发目标通过...
2017.9.29
今天上午老师继续带领我们学习视图文档结构和界面美化。文档视图结构的应用程序框架中，应用对象负责创建文档模板，而文档...
Markdown 入门
可以用来做什么应用场景：开发文档文档规范
NSLocalizedString
参考文档1参考文档2参考文档3 有些时候应用需要根据系统语言环境显示不同语言的字符，或不同的图片，或不同的应用名称...
微信分享时提示“未验证应用”
微信分享时提示“未验证应用” 先根据微信文档的指引自查请参考【腾讯文档】iOS应用出现未验证应用的问题排查 ht...
2017-9-29学习总结
星期五晴今天上午继续学习了视图文档结构和界面美化。文档视图结构的应用程序框架中，应用对象负责创建文档模板...
Kotlin学习资源大收集
教程 Kotlin Primer Kotlin在Android中的应用 Kotlin实践文档官方文档 kotl...
Kotlin资源合集(转)
教程 Kotlin Primer Kotlin在Android中的应用 Kotlin实践文档官方文档 kotl...
Electron创建应用以及打包exe
一、Electron官网文档，根据文档步骤创建应用 http://www.electronjs.org/docs/...
Peewee中文文档
Peewee中文文档【一】：安装与测试 Peewee中文文档【二】：快速开始 Peewee中文文档【三】：应用实例...

应用文档

API 应用文档

输入应用

1. 参数 (Parameters)

1. 数值型 (Numerical)

2. 字符固定型 (Fixed String)

3. 选择型 (Option)

4. 布尔型 (Boolean)

API 参数配置示例

2. 文本消息Context

1. 上下文消息 (contextMessages)

示例:

2. 最新消息 (latestMessage)

示例:

3. 输入附件 (Attachments)

附件配置文档

1. 附件 (attachments)

a. 图片 (image)

b. 文档 (doc)

c. 音频 (audio)

d. 网站URL (webURL)

示例:

输出应用文档

1. 正常响应

前端响应要求:

示例：

2. 错误处理

前端响应要求:

示例：

相关文章

网友评论

延伸阅读

深度阅读

栏目导航

热点阅读

1. 上下文消息 (`contextMessages`)

2. 最新消息 (`latestMessage`)

1. 附件 (`attachments`)

a. 图片 (`image`)

b. 文档 (`doc`)

c. 音频 (`audio`)

d. 网站URL (`webURL`)