|
| 1 | +--- |
| 2 | +Description: "" |
| 3 | +date: "2025-12-01" |
| 4 | +lastmod: "" |
| 5 | +tags: [] |
| 6 | +title: FAQ |
| 7 | +weight: 6 |
| 8 | +--- |
| 9 | + |
| 10 | +# Q: cannot use openapi3.TypeObject (untyped string constant "object") as *openapi3.Types value in struct literal; cannot use types (variable of type string) as *openapi3.Types value in struct literal |
| 11 | + |
| 12 | +Ensure the `github.com/getkin/kin-openapi` dependency version does not exceed `v0.118.0`. |
| 13 | + |
| 14 | +# Q: During agent streaming, it never reaches ToolsNode, or streaming is lost and appears non-streaming. |
| 15 | + |
| 16 | +- First, update Eino to the latest version. |
| 17 | + |
| 18 | +Different models output tool calls differently in streaming mode. Some models (e.g., OpenAI) emit tool calls directly; others (e.g., Claude) might emit text first and then the tool call. You therefore need different logic to determine whether a tool call is present in a streamed message. |
| 19 | + |
| 20 | +The ReAct Agent `Config` has a `StreamToolCallChecker`. If omitted, the agent uses a default checker that determines a tool call by inspecting whether any non-empty early chunk contains tool calls: |
| 21 | + |
| 22 | +```go |
| 23 | +func firstChunkStreamToolCallChecker(_ context.Context, sr *schema.StreamReader[*schema.Message]) (bool, error) { |
| 24 | + defer sr.Close() |
| 25 | + |
| 26 | + for { |
| 27 | + msg, err := sr.Recv() |
| 28 | + if err == io.EOF { |
| 29 | + return false, nil |
| 30 | + } |
| 31 | + if err != nil { |
| 32 | + return false, err |
| 33 | + } |
| 34 | + |
| 35 | + if len(msg.ToolCalls) > 0 { |
| 36 | + return true, nil |
| 37 | + } |
| 38 | + |
| 39 | + if len(msg.Content) == 0 { // skip empty chunks at the front |
| 40 | + continue |
| 41 | + } |
| 42 | + |
| 43 | + return false, nil |
| 44 | + } |
| 45 | +} |
| 46 | +``` |
| 47 | + |
| 48 | +This default works when the Tool Call message contains only a tool call. |
| 49 | + |
| 50 | +It does not fit cases where a non-empty content chunk appears before the tool call. In such cases, provide a custom checker like this: |
| 51 | + |
| 52 | +```go |
| 53 | +toolCallChecker := func(ctx context.Context, sr *schema.StreamReader[*schema.Message]) (bool, error) { |
| 54 | + defer sr.Close() |
| 55 | + for { |
| 56 | + msg, err := sr.Recv() |
| 57 | + if err != nil { |
| 58 | + if errors.Is(err, io.EOF) { |
| 59 | + // finish |
| 60 | + break |
| 61 | + } |
| 62 | + return false, err |
| 63 | + } |
| 64 | + if len(msg.ToolCalls) > 0 { |
| 65 | + return true, nil |
| 66 | + } |
| 67 | + } |
| 68 | + return false, nil |
| 69 | +} |
| 70 | +``` |
| 71 | + |
| 72 | +Note: this custom `StreamToolCallChecker` checks all chunks for tool calls. When the model is outputting a normal answer, this may reduce “early streaming detection”, because it waits until all chunks are inspected. To preserve streaming responsiveness, try guiding the model with prompts: |
| 73 | + |
| 74 | +> 💡 |
| 75 | +> Add prompt constraints such as: “If a tool is required, output only the tool call; do not output text.” |
| 76 | +> |
| 77 | +> Models vary in how much they adhere to such prompts. Tune and validate for your chosen model. |
| 78 | +
|
| 79 | +# Q: [github.com/bytedance/sonic/loader](http://github.com/bytedance/sonic/loader): invalid reference to runtime.lastmoduledatap |
| 80 | + |
| 81 | +Older versions of `sonic` are incompatible with `go1.24`. Upgrade to `v1.13.2` or higher. |
| 82 | + |
| 83 | +# Q: Tool input deserialization failed: `failed to invoke tool call {tool_call_id}: unmarshal input fail` |
| 84 | + |
| 85 | +Models typically do not produce invalid JSON. Investigate the specific reason for deserialization failure; in most cases this is due to output truncation when the model’s response exceeds limits. |
| 86 | + |
| 87 | +# Q: How can I implement batch processing nodes in Eino (like Coze’s batch nodes)? |
| 88 | + |
| 89 | +Eino currently does not support batch processing. Two options: |
| 90 | + |
| 91 | +1. Dynamically build the graph per request — the overhead is low. Note that `Chain Parallel` requires the number of parallel nodes to be greater than one. |
| 92 | +2. Implement a custom batch node and handle batching inside the node. |
| 93 | + |
| 94 | +# Q: Panic occurs in Fornax SDK or panic stack mentions Fornax SDK |
| 95 | + |
| 96 | +Upgrade both the Fornax SDK and Eino to the latest versions and retry. |
| 97 | + |
| 98 | +# Q: Does Eino support structured model outputs? |
| 99 | + |
| 100 | +Yes, in two steps: |
| 101 | + |
| 102 | +1. Ensure the model outputs structured data. Options: |
| 103 | + - Some models support configuration for structured output (e.g., OpenAI response format). |
| 104 | + - Use tool calls to obtain structured results. |
| 105 | + - Prompt the model explicitly to output structured data. |
| 106 | +2. After obtaining a structured message, use `schema.NewMessageJSONParser` to parse the message into your target struct. |
| 107 | + |
| 108 | +# Q: In image recognition scenarios, error: `One or more parameters specified in the request are not valid` |
| 109 | + |
| 110 | +Check whether the model supports image input (for Doubao models, only variants with `vision` support it). |
| 111 | + |
| 112 | +# Q: How to access Reasoning Content / “thinking” output from a chat model? |
| 113 | + |
| 114 | +If a model implementation supports Reasoning Content (deep thinking), it is stored in the `Extra` field of the output `Message`. The provider package usually offers helpers like `GetReasoningContent`/`GetThinking` to extract it. |
| 115 | + |
| 116 | +# Q: Errors include `context deadline exceeded`, `timeout`, or `context canceled` |
| 117 | + |
| 118 | +This indicates a timeout or that the `ctx` was canceled by a service/framework or manually. Adjust timeouts or investigate your code. If model/component latency seems abnormally high, contact the provider directly. Eino only passes through. |
| 119 | + |
| 120 | +# Q: How to access parent graph `State` within a subgraph? |
| 121 | + |
| 122 | +If both parent and subgraph have `state`, the subgraph’s state overrides the parent’s. Define a custom context key. Before invoking the subgraph, call `compose.ProcessState()` to retrieve the parent state and pass it via your custom context key. |
| 123 | + |
| 124 | +# Q: How does `eino-ext` adapt multimodal input/output for supported models? |
| 125 | + |
| 126 | +For multimodal support, see [https://www.cloudwego.io/en/docs/eino/ecosystem_integration/chat_model](https://www.cloudwego.io/en/docs/eino/ecosystem_integration/chat_model) and the corresponding examples for each model. |
| 127 | + |
| 128 | +# Q: Using `UserInputMultiContent` for multimodal input, but the model side seems to miss the data or cannot read `multicontent` |
| 129 | + |
| 130 | +Recent versions of Eino introduce `UserInputMultiContent` and `AssistantGenMultiContent` for multimodal user input and model output respectively. All `eino-ext` chat model implementations have been adapted. If the model does not receive the multimodal payload, upgrade the provider package to the latest version and try again. |
| 131 | + |
| 132 | +# Q: After upgrading to `0.6.x`, there are breaking changes |
| 133 | + |
| 134 | +Per the migration plan [Migration from OpenAPI 3.0 Schema Object to JSONSchema in Eino · Discussion #397](https://github.com/cloudwego/eino/discussions/397), Eino `v0.6.1` removed the dependency on `getkin/kin-openapi` and all OpenAPI 3.0-related code. |
| 135 | + |
| 136 | +If `eino-ext` modules error with `undefined: schema.NewParamsOneOfByOpenAPIV3`, upgrade those modules to the latest versions. |
| 137 | + |
| 138 | +If schema migration is complex, use the helper tooling in the [JSONSchema conversion guide](https://bytedance.larkoffice.com/wiki/ZMaawoQC4iIjNykzahwc6YOknXf). |
| 139 | + |
| 140 | +# Q: `context canceled` / `context deadline exceeded` |
| 141 | + |
| 142 | +The `ctx` passed to Eino was canceled or timed out; this is unrelated to the framework itself. |
| 143 | + |
0 commit comments