TextGen API 如何指定角色对话/v1/chat/completions 的 character 与 mode 参数【免费下载链接】textgenOpen-source desktop app for local LLMs. Text, vision, tool-calling, OpenAI/Anthropic-compatible API. 100% private.项目地址: https://gitcode.com/GitHub_Trending/te/textgen用 textgen 的 OpenAI 兼容 API 做对话时/v1/chat/completions除了标准的messages还接受两个本地扩展参数character指定使用哪个角色mode指定对话的格式化方式。本文以仓库自带的Example角色为例走一遍从启动 API、发起带角色的请求到验证角色确实生效的完整流程。前提是 textgen 已经安装好并可用默认在127.0.0.1:5000提供服务。准备启动 API 并加载模型给启动命令加上--api即可开启 API来源docs/12 - OpenAI API.md默认端口是 5000换端口用--api-port 1234把 1234 换成你要的端口。需要监听本地网络时加--listen。需要用密钥鉴权时加--api-key yourkey之后请求要带Authorization头见后文说明。模型不通过请求体里的model字段切换——该参数在 modules/api/typing.py 中被标注为 Unused parameter换模型要走/v1/internal/model/load端点。文档给出的示例请求文档示例model_name换成你已下载的 GGUF 文件名curl -k http://127.0.0.1:5000/v1/internal/model/load \ -H Content-Type: application/json \ -d { model_name: Qwen_Qwen3-0.6B-Q4_K_M.gguf, args: { ctx_size: 32768, cache_type: q8_0 } }也可以在 textgen 的 UI 里加载模型两者效果相同。角色从哪来user_data/characterscharacter参数的取值是 user_data/characters/ 目录下 YAML 文件的文件名不含扩展名。不传该参数时服务端使用默认的Assistant角色modules/api/typing.py 中character字段的说明原文是If not set, the default Assistant character will be used。仓库自带的两个角色可以对照看user_data/characters/Assistant.yamlname: AI带greeting和context。user_data/characters/Example.yaml文件名是Example但name字段是Chiharu Yamada。也就是说请求里写character: Example对话中的角色名会是 YAML 里的name值。角色 YAML 的字段结构以这两个文件为准name: 角色名对应请求里的 bot_name/name2 greeting: 开场白 context: 角色设定文本会作为上下文注入对话character 与 mode 的参数说明以下字段定义都来自 modules/api/typing.py 的ChatCompletionRequestParams这也是文档指向的全部端点参数类型的出处参数默认值文档中的说明character无落到AssistantA character defined under textgen/user_data/characters. If not set, the default Assistant character will be used.modeinstructValid options: instruct, chat, chat-instruct.bot_name别名name2无Overwrites the value set by character field.context无Overwrites the value set by character field.greeting无Overwrites the value set by character field.user_name别名name1YouYour name (the user). By default, its You.user_bio无The user description/personality.mode三种取值的差异可以从 modules/chat.py 的generate_chat_prompt看到instruct模式走模型的指令模板instruction template来格式化对话非instruct即chat/chat-instruct时使用聊天模板把角色名代入模板中的{{user}}/{{char}}之类占位并在context/user_bio非空时把角色设定作为 system 消息注入。docs 中的示例请求使用的就是mode: chat-instruct配角色文件所以用本地角色做角色扮演式对话时照抄示例的组合即可。另外注意 docs/12 - OpenAI API.md 的提醒/v1/chat/completionsWorks best with instruction-following models且未传instruction_template时会从模型元数据自动检测。发起带角色的对话请求docs 给出的原始示例文档示例curl http://127.0.0.1:5000/v1/chat/completions \ -H Content-Type: application/json \ -d { messages: [ { role: user, content: Hello! Who are you? } ], mode: chat-instruct, character: Example, temperature: 0.6, top_p: 0.95, top_k: 20 }其中character: Example对应user_data/characters/Example.yaml。响应结构为标准的choices[0].message.content与 docs/12 - OpenAI API.md 中 Python 示例的读取方式一致。如果服务器带--api-key启动请求需要携带鉴权头。docs 给出的 Python 写法是headers里加Authorization: Bearer yourPassword123其中密钥对应启动时的--api-key值curl 下等价于加一行-H Authorization: Bearer 你的key。验证角色是否真正生效两步验证用/v1/internal/chat-prompt端点定义于 modules/api/script.py响应模型ChatPromptResponse见 modules/api/typing.py查看最终渲染出的 prompt。它接收和/v1/chat/completions相同的请求体但不生成回复只返回{prompt: ...}。在返回的 prompt 里应能看到Example.yaml中context的内容和角色名说明角色被正确注入。curl http://127.0.0.1:5000/v1/internal/chat-prompt \ -H Content-Type: application/json \ -d { messages: [ { role: user, content: Hello! Who are you? } ], mode: chat-instruct, character: Example }发真实请求检查choices[0].message.content中的回复是否符合角色设定。docs 示例用的问法就是 Hello! Who are you?——对Example角色回复应以 YAML 中name字段对应的身份Chiharu Yamada自述而不是默认的 AI 助手。可选不改角色文件在请求里覆盖角色字段不想新建角色文件时可以用bot_name、context、greeting三个参数在单个请求里覆盖角色文件的取值modules/api/completions.py 中的取值顺序是请求参数优先缺省回落到角色文件。例如把角色临时改名叫 Novacurl http://127.0.0.1:5000/v1/chat/completions \ -H Content-Type: application/json \ -d { messages: [ { role: user, content: Who are you? } ], mode: chat-instruct, character: Example, bot_name: Nova }user_name/user_bio则用来描述对话另一方默认 You。限制与注意functions和function_call参数会被直接拒绝modules/api/completions.py 抛出 functions is not supported.工具调用要走tools参数那是 docs 中另一个独立主题。character取值写错文件名不存在时文档没有给出对应的报错行为建议先用/v1/internal/chat-prompt检查渲染结果里是否出现预期角色再发正式请求。端口、鉴权等全局行为以 docs/12 - OpenAI API.md 为准完整端点和参数类型可在服务启动后访问http://127.0.0.1:5000/docs查看。【免费下载链接】textgenOpen-source desktop app for local LLMs. Text, vision, tool-calling, OpenAI/Anthropic-compatible API. 100% private.项目地址: https://gitcode.com/GitHub_Trending/te/textgen创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考