Skip to content

Commit 1adeaf9

Browse files
zhuangjie1125zhuangjie1125
authored
feat(eino): add chat model readme docs for en & update chat model readme for cn (#1473)
1 parent 36b1f07 commit 1adeaf9

18 files changed

+6747
-1371
lines changed

‎content/en/docs/eino/ecosystem_integration/chat_model/chat_model_ark.md‎

Lines changed: 1201 additions & 176 deletions
Large diffs are not rendered by default.

‎content/en/docs/eino/ecosystem_integration/chat_model/chat_model_arkbot.md‎

Lines changed: 339 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,339 @@
1+
---
2+
Description: ""
3+
date: "2025-12-02"
4+
lastmod: ""
5+
tags: []
6+
title: ChatModel - arkbot
7+
weight: 0
8+
---
9+
10+
A Volcengine Ark Bot implementation for [Eino](https://github.com/cloudwego/eino) that implements the `ToolCallingChatModel` interface. This enables seamless integration with Eino's LLM capabilities for enhanced natural language processing and generation.
11+
12+
## Features
13+
14+
- Implements `github.com/cloudwego/eino/components/model.ToolCallingChatModel`
15+
- Easy integration with Eino's model system
16+
- Configurable model parameters
17+
- Support for chat completion
18+
- Support for streaming responses
19+
- Custom response parsing support
20+
- Flexible model configuration
21+
22+
## Installation
23+
24+
```bash
25+
go get github.com/cloudwego/eino-ext/components/model/arkbot@latest
26+
```
27+
28+
## Quick Start
29+
30+
Here's a quick example of how to use the Ark Bot:
31+
32+
```go
33+
34+
package main
35+
36+
import (
37+
"context"
38+
"encoding/json"
39+
"log"
40+
"os"
41+
42+
"github.com/cloudwego/eino/schema"
43+
44+
"github.com/cloudwego/eino-ext/components/model/arkbot"
45+
)
46+
47+
func main() {
48+
ctx := context.Background()
49+
50+
// Get ARK_API_KEY and ARK_MODEL_ID: https://www.volcengine.com/docs/82379/1399008
51+
chatModel, err := arkbot.NewChatModel(ctx, &arkbot.Config{
52+
APIKey: os.Getenv("ARK_API_KEY"),
53+
Model: os.Getenv("ARK_MODEL_ID"),
54+
})
55+
56+
if err != nil {
57+
log.Fatalf("NewChatModel failed, err=%v", err)
58+
}
59+
60+
inMsgs := []*schema.Message{
61+
{
62+
Role: schema.User,
63+
Content: "What's the weather in Beijing?",
64+
},
65+
}
66+
67+
msg, err := chatModel.Generate(ctx, inMsgs)
68+
if err != nil {
69+
log.Fatalf("Generate failed, err=%v", err)
70+
}
71+
72+
log.Printf("generate output: \n")
73+
log.Printf(" request_id: %s\n", arkbot.GetArkRequestID(msg))
74+
if bu, ok := arkbot.GetBotUsage(msg); ok {
75+
bbu, _ := json.Marshal(bu)
76+
log.Printf(" bot_usage: %s\n", string(bbu))
77+
}
78+
if ref, ok := arkbot.GetBotChatResultReference(msg); ok {
79+
bRef, _ := json.Marshal(ref)
80+
log.Printf(" bot_chat_result_reference: %s\n", bRef)
81+
}
82+
respBody, _ := json.MarshalIndent(msg, " ", " ")
83+
log.Printf(" body: %s\n", string(respBody))
84+
}
85+
86+
87+
```
88+
89+
## Configuration
90+
91+
The model can be configured using the `arkbot.Config` struct:
92+
93+
```go
94+
95+
type Config struct {
96+
// Timeout specifies the maximum duration to wait for API responses
97+
// If HTTPClient is set, Timeout will not be used.
98+
// Optional. Default: 10 minutes
99+
Timeout *time.Duration `json:"timeout"`
100+
101+
// HTTPClient specifies the client to send HTTP requests.
102+
// If HTTPClient is set, Timeout will not be used.
103+
// Optional. Default &http.Client{Timeout: Timeout}
104+
HTTPClient *http.Client `json:"http_client"`
105+
106+
// RetryTimes specifies the number of retry attempts for failed API calls
107+
// Optional. Default: 2
108+
RetryTimes *int `json:"retry_times"`
109+
110+
// BaseURL specifies the base URL for Ark service
111+
// Optional. Default: "https://ark.cn-beijing.volces.com/api/v3"
112+
BaseURL string `json:"base_url"`
113+
// Region specifies the region where Ark service is located
114+
// Optional. Default: "cn-beijing"
115+
Region string `json:"region"`
116+
117+
// The following three fields are about authentication - either APIKey or AccessKey/SecretKey pair is required
118+
// For authentication details, see: https://www.volcengine.com/docs/82379/1298459
119+
// APIKey takes precedence if both are provided
120+
APIKey string `json:"api_key"`
121+
AccessKey string `json:"access_key"`
122+
SecretKey string `json:"secret_key"`
123+
124+
// The following fields correspond to Ark's chat completion API parameters
125+
// Ref: https://www.volcengine.com/docs/82379/1298454
126+
127+
// Model specifies the ID of endpoint on ark platform
128+
// Required
129+
Model string `json:"model"`
130+
131+
// MaxTokens limits the maximum number of tokens that can be generated in the chat completion.
132+
// Optional. Default: 4096
133+
MaxTokens *int `json:"max_tokens,omitempty"`
134+
135+
// Temperature specifies what sampling temperature to use
136+
// Generally recommend altering this or TopP but not both
137+
// Range: 0.0 to 1.0. Higher values make output more random
138+
// Optional. Default: 1.0
139+
Temperature *float32 `json:"temperature,omitempty"`
140+
141+
// TopP controls diversity via nucleus sampling
142+
// Generally recommend altering this or Temperature but not both
143+
// Range: 0.0 to 1.0. Lower values make output more focused
144+
// Optional. Default: 0.7
145+
TopP *float32 `json:"top_p,omitempty"`
146+
147+
// Stop sequences where the API will stop generating further tokens
148+
// Optional. Example: []string{"\n", "User:"}
149+
Stop []string `json:"stop,omitempty"`
150+
151+
// FrequencyPenalty prevents repetition by penalizing tokens based on frequency
152+
// Range: -2.0 to 2.0. Positive values decrease likelihood of repetition
153+
// Optional. Default: 0
154+
FrequencyPenalty *float32 `json:"frequency_penalty,omitempty"`
155+
156+
// LogitBias modifies likelihood of specific tokens appearing in completion
157+
// Optional. Map token IDs to bias values from -100 to 100
158+
LogitBias map[string]int `json:"logit_bias,omitempty"`
159+
160+
// PresencePenalty prevents repetition by penalizing tokens based on presence
161+
// Range: -2.0 to 2.0. Positive values increase likelihood of new topics
162+
// Optional. Default: 0
163+
PresencePenalty *float32 `json:"presence_penalty,omitempty"`
164+
165+
// CustomHeader the http header passed to model when requesting model
166+
CustomHeader map[string]string `json:"custom_header"`
167+
168+
// LogProbs specifies whether to return log probabilities of the output tokens.
169+
LogProbs bool `json:"log_probs"`
170+
171+
// TopLogProbs specifies the number of most likely tokens to return at each token position, each with an associated log probability.
172+
TopLogProbs int `json:"top_log_probs"`
173+
174+
// ResponseFormat specifies the format that the model must output.
175+
ResponseFormat *ResponseFormat `json:"response_format,omitempty"`
176+
}
177+
```
178+
179+
## Request Options
180+
181+
The Ark model supports various request options to customize the behavior of API calls. Here are the available options:
182+
183+
```go
184+
// WithCustomHeader sets custom headers for a single request
185+
// the headers will override all the headers given in ChatModelConfig.CustomHeader
186+
func WithCustomHeader(m map[string]string) model.Option {}
187+
```
188+
189+
190+
## examples
191+
192+
### generate
193+
194+
```go
195+
196+
package main
197+
198+
import (
199+
"context"
200+
"encoding/json"
201+
"log"
202+
"os"
203+
204+
"github.com/cloudwego/eino/schema"
205+
206+
"github.com/cloudwego/eino-ext/components/model/arkbot"
207+
)
208+
209+
func main() {
210+
ctx := context.Background()
211+
212+
// Get ARK_API_KEY and ARK_MODEL_ID: https://www.volcengine.com/docs/82379/1399008
213+
chatModel, err := arkbot.NewChatModel(ctx, &arkbot.Config{
214+
APIKey: os.Getenv("ARK_API_KEY"),
215+
Model: os.Getenv("ARK_MODEL_ID"),
216+
})
217+
218+
if err != nil {
219+
log.Fatalf("NewChatModel failed, err=%v", err)
220+
}
221+
222+
inMsgs := []*schema.Message{
223+
{
224+
Role: schema.User,
225+
Content: "What's the weather in Beijing?",
226+
},
227+
}
228+
229+
msg, err := chatModel.Generate(ctx, inMsgs)
230+
if err != nil {
231+
log.Fatalf("Generate failed, err=%v", err)
232+
}
233+
234+
log.Printf("generate output: \n")
235+
log.Printf(" request_id: %s\n", arkbot.GetArkRequestID(msg))
236+
if bu, ok := arkbot.GetBotUsage(msg); ok {
237+
bbu, _ := json.Marshal(bu)
238+
log.Printf(" bot_usage: %s\n", string(bbu))
239+
}
240+
if ref, ok := arkbot.GetBotChatResultReference(msg); ok {
241+
bRef, _ := json.Marshal(ref)
242+
log.Printf(" bot_chat_result_reference: %s\n", bRef)
243+
}
244+
respBody, _ := json.MarshalIndent(msg, " ", " ")
245+
log.Printf(" body: %s\n", string(respBody))
246+
}
247+
248+
```
249+
250+
### stream
251+
252+
```go
253+
254+
package main
255+
256+
import (
257+
"context"
258+
"encoding/json"
259+
"fmt"
260+
"io"
261+
"log"
262+
"os"
263+
264+
"github.com/cloudwego/eino/schema"
265+
266+
"github.com/cloudwego/eino-ext/components/model/arkbot"
267+
)
268+
269+
func main() {
270+
ctx := context.Background()
271+
272+
// Get ARK_API_KEY and ARK_MODEL_ID: https://www.volcengine.com/docs/82379/1399008
273+
chatModel, err := arkbot.NewChatModel(ctx, &arkbot.Config{
274+
APIKey: os.Getenv("ARK_API_KEY"),
275+
Model: os.Getenv("ARK_MODEL_ID"),
276+
})
277+
if err != nil {
278+
log.Printf("NewChatModel failed, err=%v", err)
279+
return
280+
}
281+
282+
streamMsgs, err := chatModel.Stream(ctx, []*schema.Message{
283+
{
284+
Role: schema.User,
285+
Content: "What's the weather in Beijing?",
286+
},
287+
})
288+
289+
if err != nil {
290+
log.Printf("Generate failed, err=%v", err)
291+
return
292+
}
293+
294+
defer streamMsgs.Close() // do not forget to close the stream
295+
296+
msgs := make([]*schema.Message, 0)
297+
298+
log.Printf("stream output:")
299+
for {
300+
msg, err := streamMsgs.Recv()
301+
if err == io.EOF {
302+
break
303+
}
304+
msgs = append(msgs, msg)
305+
if err != nil {
306+
log.Printf("\nstream.Recv failed, err=%v", err)
307+
return
308+
}
309+
fmt.Print(msg.Content)
310+
}
311+
312+
msg, err := schema.ConcatMessages(msgs)
313+
if err != nil {
314+
log.Printf("ConcatMessages failed, err=%v", err)
315+
return
316+
}
317+
318+
log.Printf("generate output: \n")
319+
log.Printf(" request_id: %s\n", arkbot.GetArkRequestID(msg))
320+
if bu, ok := arkbot.GetBotUsage(msg); ok {
321+
bbu, _ := json.Marshal(bu)
322+
log.Printf(" bot_usage: %s\n", string(bbu))
323+
}
324+
if ref, ok := arkbot.GetBotChatResultReference(msg); ok {
325+
bRef, _ := json.Marshal(ref)
326+
log.Printf(" bot_chat_result_reference: %s\n", bRef)
327+
}
328+
respBody, _ := json.MarshalIndent(msg, " ", " ")
329+
log.Printf(" body: %s\n", string(respBody))
330+
}
331+
332+
```
333+
334+
335+
336+
## For More Details
337+
338+
- [Eino Documentation](https://www.cloudwego.io/zh/docs/eino/)
339+
- [Volcengine Ark Model Documentation](https://www.volcengine.com/docs/82379/1263272)

0 commit comments

Comments
 (0)