Documentation
¶
Overview ¶
Package openai 封装一些调用 OpenAI 兼容协议的能力
Index ¶
- func AddImageDataToLastMessage(messages []openai.ChatCompletionMessage, data []byte) ([]openai.ChatCompletionMessage, error)
- func AddImageURLToLastMessage(messages []openai.ChatCompletionMessage, url string) ([]openai.ChatCompletionMessage, error)
- func AddOrSetPromptForMessages(messages []openai.ChatCompletionMessage, prompt string) []openai.ChatCompletionMessage
- func MergeResponseDeltaChunks(chunks ...openai.ChatCompletionStreamResponse) (response openai.ChatCompletionStreamResponse, mergedCount int)
- func NewMCPCallToolResultWithJSON(v any) (*mcp.CallToolResult, error)
- func NewMCPCallToolResultWithString(s string) (*mcp.CallToolResult, error)
- func ReadMCPCallToolRequest[T any](req mcp.CallToolRequest) (T, error)
- type ConversationRound
- type InitializedMCPClient
- type MCPToolBuilder
- type ModelConfig
- type Option
- func WithAnthropic() Option
- func WithContentCallback(c func(delta string)) Option
- func WithDebugger(d func(string, ...any)) Option
- func WithExtraFields(fields any) Option
- func WithFinishCallback(c func(openai.FinishReason)) Option
- func WithHeader(h http.Header) Option
- func WithIncludeUsage() Option
- func WithInitializedMCP(c InitializedMCPClient, id string) Option
- func WithInitializedMCPAndSpecifyTools(c InitializedMCPClient, id string, tools ...string) Option
- func WithPreRequestCallback(c PreRequestCallback) Option
- func WithReasoningCallback(c func(delta string)) Option
- func WithRemoteMCP(baseURL string, id string, opts ...transport.ClientOption) Option
- func WithRemoteMCPAndSpecifyTools(baseURL string, id string, toolsAndOpts ...any) Option
- func WithResponseChunkCallback(c func(openai.ChatCompletionStreamResponse)) Option
- func WithToolCallRequestCallback(c func(openai.ToolCall)) Option
- func WithToolCallResponseCallback(c func(openai.ChatCompletionMessage)) Option
- func WithTools(tools ToolManager, id string) Option
- type PreRequestCallback
- type PreRequestContext
- type ProcessResponse
- type SkillInfo
- type SkillMetadata
- type ToolManager
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddImageDataToLastMessage ¶
func AddImageDataToLastMessage( messages []openai.ChatCompletionMessage, data []byte, ) ([]openai.ChatCompletionMessage, error)
AddImageDataToLastMessage 为最后一个消息添加图片数据, 可能修改 message 中的数据。
如果 messages 中没有成员, 会报错退出
func AddImageURLToLastMessage ¶
func AddImageURLToLastMessage( messages []openai.ChatCompletionMessage, url string, ) ([]openai.ChatCompletionMessage, error)
AddImageURLToLastMessage 为最后一个消息添加图片 URL, 可能修改 message 中的数据
如果 messages 中没有成员, 会报错退出
func AddOrSetPromptForMessages ¶
func AddOrSetPromptForMessages( messages []openai.ChatCompletionMessage, prompt string, ) []openai.ChatCompletionMessage
AddOrSetPromptForMessages 添加或设置整个上下文的。如果 prompt 不存在则设置, 存在则替换
func MergeResponseDeltaChunks ¶
func MergeResponseDeltaChunks( chunks ...openai.ChatCompletionStreamResponse, ) (response openai.ChatCompletionStreamResponse, mergedCount int)
MergeResponseDeltaChunks 合并多个 SSE 响应段,从 chunks[0] 开始做前缀合并, 遇到格式不同时立即停止,返回已合并的结果和合并个数。调用方可用 mergedCount 切掉已处理的前缀,再对剩余 chunks 继续调用以拆分后续段。
注意: 本函数仅处理 Choices[0] 的 delta,多 choice 场景不适用。
delta 内容按语义分为以下几类,同类才合并:
- empty/role-only:空 delta 或仅含 role 字段,透明地吸收进后续包。
- reasoning:Delta.ReasoningContent != ""
- content:Delta.Content != ""
- tool_calls:len(Delta.ToolCalls) > 0,连续的 tool_calls 包(含跨 index)合并为同一段。
- finish:Choices[0].FinishReason != "",单独成段,不与其他类型合并。
- usage:len(Choices)==0 且 Usage != nil
- mixed:同时含多种实质内容类型,单独成段,不与其他类型合并。
字段合并规则:
- ID / Object / Created / Model / SystemFingerprint:取第一个包的值
- Usage:取最后一个非 nil 的值
- Choices[0].FinishReason:取最后一个非空的值
- Choices[0].Delta.Role:取第一个非空的值
- Choices[0].Delta.Content / ReasoningContent:拼接
- Choices[0].Delta.ToolCalls:按 Index 合并,Arguments 拼接;新 Index 追加
func NewMCPCallToolResultWithJSON ¶
func NewMCPCallToolResultWithJSON(v any) (*mcp.CallToolResult, error)
NewMCPCallToolResultWithJSON 生成一个 MCP 工具调用结果, 使用 json.Marshal 之后的数据 打包为 JSON 数据, 用于适配 InitializedMCPClient 接口
func NewMCPCallToolResultWithString ¶
func NewMCPCallToolResultWithString(s string) (*mcp.CallToolResult, error)
NewMCPCallToolResultWithString 生成一个 MCP 工具调用结果, 用于适配 InitializedMCPClient 接口
func ReadMCPCallToolRequest ¶
func ReadMCPCallToolRequest[T any](req mcp.CallToolRequest) (T, error)
ReadMCPCallToolRequest 读取 MCP 工具调用参数, 方便实现 InitializedMCPClient 接口。
Types ¶
type ConversationRound ¶
type ConversationRound struct {
Request openai.ChatCompletionRequest `json:"request,omitempty"`
Response openai.ChatCompletionResponse `json:"response,omitempty"`
}
ConversationRound 表示一轮对话请求和响应
type InitializedMCPClient ¶
type InitializedMCPClient interface {
ListTools(ctx context.Context, request mcp.ListToolsRequest) (*mcp.ListToolsResult, error)
CallTool(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error)
}
InitializedMCPClient 表示一个已经初始化完毕的 MCP 客户端
type MCPToolBuilder ¶
func MCPToolParamWithBoolean ¶
func MCPToolParamWithBoolean(name string, required bool, desc string) MCPToolBuilder
MCPToolParamWithBoolean 创建一个 MCP boolean 参数构建器, 用于构建 MCP tool 列表参数
func MCPToolParamWithNumber ¶
func MCPToolParamWithNumber(name string, required bool, desc string) MCPToolBuilder
MCPToolParamWithNumber 创建一个 MCP 数字参数构建器, 用于构建 MCP tool 列表参数
func MCPToolParamWithString ¶
func MCPToolParamWithString(name string, required bool, desc string) MCPToolBuilder
MCPToolParamWithString 创建一个 MCP string 参数构建器, 用于构建 MCP tool 列表参数
type ModelConfig ¶
type ModelConfig struct {
Model string `json:"model,omitempty"`
BaseURL string `json:"base_url,omitempty"`
APIKey string `json:"api_key,omitempty"`
}
ModelConfig 模型配置
type Option ¶
type Option func(*options)
Option 额外选项
func WithAnthropic ¶
func WithAnthropic() Option
WithAnthropic 在请求时转换为 Anthropic 协议并发往 /v1/messages 端点,拿到响应后转换回 OpenAI 协议。ModelConfig.BaseURL 应设置为完整的 Anthropic 端点 URL,例如 "https://api.anthropic.com/v1/messages"。
注意事项:
- extra fields 中的字段会直接注入到 Anthropic 请求 JSON 中,其中 stop → stop_sequences 会自动映射
- 若需要设置 anthropic-beta 等 header,请使用 WithHeader()
- 建议不要通过 WithExtraFields 设置 tool_choice,库会自动处理工具调用格式
func WithContentCallback ¶
WithContentCallback 设置内容回调函数
func WithExtraFields ¶
WithExtraFields 设置请求 completion 的额外参数。后设置的会覆盖前面设置的 key。 如果传入的参数不是一个有效的 JSON object, 则不进行设置
func WithFinishCallback ¶
func WithFinishCallback(c func(openai.FinishReason)) Option
WithFinishCallback 设置 (阶段性的) 结束回调函数
func WithHeader ¶
WithHeader 设置自定义 HTTP header,会覆盖默认 header 中的同名字段。 常用于设置 anthropic-version、anthropic-beta 等 Anthropic 专用 header。
func WithInitializedMCP ¶
func WithInitializedMCP(c InitializedMCPClient, id string) Option
WithInitializedMCP 设置自定义的已初始化完成的 MCP 客户端, 可以设置多个 参数 id 可以是任意不含空格和毛好的字符串, 多个 MCP 之间不得重复
func WithInitializedMCPAndSpecifyTools ¶
func WithInitializedMCPAndSpecifyTools(c InitializedMCPClient, id string, tools ...string) Option
WithInitializedMCPAndSpecifyTools 同 WithInitializedMCP, 但明确指定只引用其中的某些工具。
func WithPreRequestCallback ¶
func WithPreRequestCallback(c PreRequestCallback) Option
WithPreRequestCallback 设置准备发出请求之前的回调函数, 支持调用方直接改写底层 messages。 传入 nil 时不覆盖已有回调。
func WithReasoningCallback ¶
WithReasoningCallback 设置思考内容回调函数
func WithRemoteMCP ¶
func WithRemoteMCP(baseURL string, id string, opts ...transport.ClientOption) Option
WithRemoteMCP 设置远程 MCP 的 URL, 可以设置多个。 参数 id 可以是任意不含空格和毛好的字符串, 多个 MCP 之间不得重复
func WithRemoteMCPAndSpecifyTools ¶
WithRemoteMCPAndSpecifyTools 的功能等同于 WithRemoteMCP, 但明确指定只引用其中的某些工具。
func WithResponseChunkCallback ¶
func WithResponseChunkCallback(c func(openai.ChatCompletionStreamResponse)) Option
WithResponseChunkCallback 设置一次 SSE 响应的回调函数
func WithToolCallRequestCallback ¶
WithToolCallRequestCallback 设置工具调用请求回调函数
func WithToolCallResponseCallback ¶
func WithToolCallResponseCallback(c func(openai.ChatCompletionMessage)) Option
WithToolCallResponseCallback 设置工具调用响应回调函数
type PreRequestCallback ¶
type PreRequestCallback func( ctx context.Context, params *PreRequestContext, ) error
PreRequestCallback 表示准备发出请求之前的回调函数, 支持调用方直接改写底层 messages。 每次向模型发起请求前都会调用(含工具调用后的后续轮次)。最终发出的消息是否正确由回调方自行负责。
type PreRequestContext ¶
type PreRequestContext struct {
RequestMessages []openai.ChatCompletionMessage
}
PreRequestContext 表示准备发出请求之前的参数。 RequestMessages 即处理器当前持有的消息切片,回调可原地修改元素,也可整体替换该切片。
type ProcessResponse ¶
type ProcessResponse struct {
Messages []openai.ChatCompletionMessage
FinishReason openai.FinishReason
FullConversation []ConversationRound
}
ProcessResponse 表示一次请求的结果
func Process ¶
func Process( ctx context.Context, config ModelConfig, messages []openai.ChatCompletionMessage, options ...Option, ) (ProcessResponse, error)
Process 完全自助式地处理一次完整的流式响应, 从发起请求开始, 自动调用工具, 直到模型返回完成为止
type SkillInfo ¶
type SkillInfo struct {
Metadata SkillMetadata
Dir string
}
SkillInfo 表示一个包含 SKILL.md skill
func ListAllSkills ¶
ListAllSkills 列出指定目录下的所有 SKILL.md 文件
type SkillMetadata ¶
SkillMetadata 表示一个 SKILL.md 的 metadata 部分
type ToolManager ¶
type ToolManager InitializedMCPClient
ToolManager 表示一个工具管理器。实际上 MCP 也只不过是 tool call 的封装,这里只是借用 mcp package 来包装一些字段
func ToolsForSkill ¶
func ToolsForSkill() ToolManager
ToolsForSkill 返回两个可用于 SKILL 能力的工具: Read 和 Bash。请注意: 这仅适用于类 UNIX