跳到正文
Yayin Story Studio Yayin Story Studio 项目文档

Contents

Visindigo::Agent::Model Class

class Visindigo::Agent::Model

一个可被请求的模型端点. 详情...

头文件： #include <Agent/Model.h>
自以下版本： Visindigo 0.17.0

公开类型

flags Capabilities
(自 Visindigo 0.17.0 引入) enum class Capability { None, Text, Image, Audio, ToolUse }

公开成员函数

(自 Visindigo 0.17.0 引入) Model()
(自 Visindigo 0.17.0 引入) ~Model()
(自 Visindigo 0.17.0 引入) Visindigo::Agent::Model &addCapability(Visindigo::Agent::Model::Capability capability)
(自 Visindigo 0.17.0 引入) bool fromJson(const Visindigo::Utility::JsonConfig &json)
(自 Visindigo 0.17.0 引入) Visindigo::Agent::Model::Capabilities getCapabilities() const
(自 Visindigo 0.17.0 引入) QString getId() const
(自 Visindigo 0.17.0 引入) qint32 getIdleTimeoutMs() const
(自 Visindigo 0.17.0 引入) QString getName() const
(自 Visindigo 0.17.0 引入) Visindigo::Utility::JsonConfig getParameters() const
(自 Visindigo 0.17.0 引入) qint32 getTimeoutMs() const
(自 Visindigo 0.17.0 引入) QString getToken() const
(自 Visindigo 0.17.0 引入) QUrl getUrl() const
(自 Visindigo 0.17.0 引入) bool hasCapability(Visindigo::Agent::Model::Capability capability) const
(自 Visindigo 0.17.0 引入) bool isValid() const
(自 Visindigo 0.17.0 引入) Visindigo::Agent::Model &setCapabilities(Visindigo::Agent::Model::Capabilities capabilities)
(自 Visindigo 0.17.0 引入) Visindigo::Agent::Model &setIdleTimeoutMs(qint32 ms)
(自 Visindigo 0.17.0 引入) Visindigo::Agent::Model &setMaxTokens(qint32 value)
(自 Visindigo 0.17.0 引入) Visindigo::Agent::Model &setName(const QString &name)
(自 Visindigo 0.17.0 引入) Visindigo::Agent::Model &setParameter(const QString &key, const QJsonValue &value)
(自 Visindigo 0.17.0 引入) Visindigo::Agent::Model &setTemperature(qreal value)
(自 Visindigo 0.17.0 引入) Visindigo::Agent::Model &setTimeoutMs(qint32 ms)
(自 Visindigo 0.17.0 引入) Visindigo::Agent::Model &setToken(const QString &token)
(自 Visindigo 0.17.0 引入) Visindigo::Agent::Model &setTopP(qreal value)
(自 Visindigo 0.17.0 引入) Visindigo::Agent::Model &setUrl(const QUrl &url)
(自 Visindigo 0.17.0 引入) Visindigo::Utility::JsonConfig toJson() const

详细说明

Model 描述"请求该发到哪里、用哪个凭据、默认参数是什么"，它不持有任何会话 状态。会话状态属于 Dialog。

模型用 getId() 返回的 UUID 作为唯一标识，并注册在 Visindigo::Agent::Center 的模型池里；Provider 与 Dialog 都只持有 这个 id。之所以不把 Model 直接嵌进 Provider，是因为 Model 里带着凭据： 如果 Provider 持有 Model 的副本，那么 token 会随 Provider 的每一次拷贝、 每一次序列化扩散到各处，轮换凭据时就必须把所有副本翻出来改。id 索引把 凭据收敛到唯一一份。

Capability 描述该端点能接受哪些类型的输入。它不是装饰性的自我声明， 而是给 Provider::pickFirst() 用来筛选的：当一次对话需要图片输入，而 当前模型只声明了 Capability::Text 时，正确的做法是换一个模型，而不是 把图片发给一个不支持它的端点——后者通常会得到一句含糊的 400。

Note: 这里只描述 OpenAI 兼容的请求形态。Model 不区分厂商，凡是遵循同一套 请求/响应结构的端点都可以用它描述。

成员类型文档

[since Visindigo 0.17.0] enum class Model::Capability
flags Model::Capabilities

模型能力位标志。取值可以按位或组合，因此它是一个 QFlags 而不是普通枚举。

ConstantValueDescription
Visindigo::Agent::Model::Capability::None0无任何能力。仅作为 0 使用，正常情况下不应该出现。
Visindigo::Agent::Model::Capability::Text1 << 0接受纯文本输入。这是所有对话模型的最低要求。
Visindigo::Agent::Model::Capability::Image1 << 1接受图片输入（视觉模型）。
Visindigo::Agent::Model::Capability::Audio1 << 2接受音频输入。
Visindigo::Agent::Model::Capability::ToolUse1 << 3支持工具调用，即请求里的 tools 字段会被认真处理， 而不是被忽略或报错。声明了工具却得不到调用，最常见的原因就是漏了这个位。

这个enum 从 Visindigo 0.17.0 开始支持。

Capabilities 类型是 QFlags<Capability> 的一个类型别名。它存储了多个 Capability 值的OR组合，可供安全计算。

成员函数文档

[since Visindigo 0.17.0] Model::Model()

构造一个空模型，并立即分配一个新的 UUID。

Note: id 在构造时一次性生成，之后不再由外部修改；fromJson() 是唯一的 例外，它会用存档里的 id 覆盖当前值。

这个function 从 Visindigo 0.17.0 开始支持。

[noexcept, since Visindigo 0.17.0] Model::~Model()

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Agent::Model &Model::addCapability(Visindigo::Agent::Model::Capability capability)

追加一个能力位，不影响已声明的能力。

capability 要追加的能力位。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] bool Model::fromJson(const Visindigo::Utility::JsonConfig &json)

从 JSON 对象恢复。

存档里带有 id 时会一并恢复，这是 id 唯一的赋值入口；没有 id 字段时保留 当前（新生成的）id，因而把一个只写了连接信息的手写配置文件读进来也能得到 一个可用的模型。

json 应当是 toJson() 的输出，或者结构相同的手写配置。

return 读到了非空的 id 时返回 true。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Agent::Model::Capabilities Model::getCapabilities() const

返回已声明的全部能力位。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] QString Model::getId() const

返回模型的唯一标识。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] qint32 Model::getIdleTimeoutMs() const

返回空闲超时，单位毫秒。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] QString Model::getName() const

返回模型名。

Note: 它是服务端的模型标识，不是本地别名。见 setName()。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Utility::JsonConfig Model::getParameters() const

把全部模型参数导出为一个 JSON 对象。点号路径的键在导出时会被还原成嵌套结构。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] qint32 Model::getTimeoutMs() const

返回请求总时长上限，单位毫秒。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] QString Model::getToken() const

返回访问凭据。

Warning: 不要把它的返回值写进日志或错误提示。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] QUrl Model::getUrl() const

返回服务基地址。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] bool Model::hasCapability(Visindigo::Agent::Model::Capability capability) const

判断是否声明了指定能力。多个位需要同时满足时，调用方应当自行用 Capabilities 做整体比较，本函数只检查单个位。

capability 要检查的能力位。

return 声明了该能力位时返回 true。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] bool Model::isValid() const

判断模型描述是否足够发起一次请求：需要非空模型名、合法的绝对 URL， 以及非空凭据。

Note: 这里不检查 URL 是否真的可达——那属于运行期的事，配置阶段无从得知。

return 模型名、URL 与凭据都齐全时返回 true。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Agent::Model &Model::setCapabilities(Visindigo::Agent::Model::Capabilities capabilities)

整体替换能力声明。传入 Capability::None 相当于声明"什么都不能做"， 该模型将无法被任何 Provider::pickFirst() 选中。

capabilities 完整的能力位组合。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Agent::Model &Model::setIdleTimeoutMs(qint32 ms)

设置两次数据到达之间的最大间隔，单位毫秒。0 表示使用执行层的默认值。

这是流式请求真正需要的超时：模型思考时可能长时间不吐字，但只要连接还活着 就不该判定失败，而连接真断了又必须尽快发现。

ms 空闲超时，单位毫秒；0 表示使用执行层的默认值。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Agent::Model &Model::setMaxTokens(qint32 value)

设置单次回复的输出上限。等价于 setParameter() 写入 "max_tokens"。

Note: 这是输出上限，不是上下文上限；两者的字段名在不同服务端并不统一， 因此这里只提供最常见的一种写法。

value 输出上限（token 数）。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Agent::Model &Model::setName(const QString &name)

设置模型名，即请求体里 model 字段的值，例如 deepseek-flash。

名称必须与服务端的取值完全一致，写错时服务端会直接拒绝请求。它同时 也作为界面上的展示名——模型标识本来就该是自解释的，另起一个别名只会 让配置与错误提示对不上。

Note: 名称不参与索引，索引一律走 id；同名模型可以共存。

name 模型名，即请求体里 model 字段的值。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Agent::Model &Model::setParameter(const QString &key, const QJsonValue &value)

设置一个原样并入请求体的模型参数，例如 "frequency_penalty": 0.5。

key 支持 "a.b" 形式的点号路径，用于写入嵌套对象。

这类参数不做任何校验与改名，因此当服务端新增某个采样参数时不需要改动 Visindigo，直接在配置里写出来即可。代价是拼错的键不会被发现——服务端 多半会静默忽略它。

value 参数值，原样写入请求体。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Agent::Model &Model::setTemperature(qreal value)

设置 temperature。等价于 setParameter() 写入 "temperature"。

这是常用的采样参数，因此单独给一个入口，省得调用方自己拼 JSON 值。

value 采样温度。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Agent::Model &Model::setTimeoutMs(qint32 ms)

设置单次请求的总时长上限，单位毫秒。0 表示不限。

Warning: 对话请求通常是流式的，总时长上限会随模型输出长度自然增长。 对流式请求应当依赖 setIdleTimeoutMs() 而不是这个值，否则一段较长的 回答会在中途被整体掐断。

ms 总时长上限，单位毫秒；0 表示不限。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Agent::Model &Model::setToken(const QString &token)

设置访问凭据，将以 Authorization: Bearer 头的形式发出。

Warning: 凭据是明文保存在 Model 里的，而 Model 会被序列化。把带凭据的 配置写进版本库或随程序分发都会直接泄露它；正确做法是让配置停留在用户 自己机器的目录下。

token 访问凭据。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Agent::Model &Model::setTopP(qreal value)

设置 top_p。等价于 setParameter() 写入 "top_p"。

value top_p 取值。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Agent::Model &Model::setUrl(const QUrl &url)

设置服务基地址，例如 https://api.deepseek.com。

这里应当填基地址而不是完整的对话端点：具体的 /chat/completions 由 执行层在拼装请求时追加，这样同一个 Model 描述就还能用于列出模型、 计数 token 之类的旁路请求。

url 服务基地址，不带具体端点路径。

这个function 从 Visindigo 0.17.0 开始支持。

[since Visindigo 0.17.0] Visindigo::Utility::JsonConfig Model::toJson() const

序列化为 JSON 对象，包含 id、连接信息、能力位与全部模型参数。

Warning: 返回值里含有明文凭据，见 setToken() 的警告。

这个function 从 Visindigo 0.17.0 开始支持。