Skip to content

Commit 9a94a33

Browse files
songgotsonggot
committed
[API] Add ML LXM Service API(internal) for large model interactons
This commit introduces the ML LXM Service API, a new C API designed to facilitate interactions with large-scale models such as Large Language Models (LLMs) Signed-off-by: hyunil park <hyunil46.park@samsung.com>
1 parent 71aaab1 commit 9a94a33

File tree

3 files changed

+601
-1
lines changed

3 files changed

+601
-1
lines changed

‎c/include/ml-lxm-service-internal.h‎

Lines changed: 283 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,283 @@
1+
/* SPDX-License-Identifier: Apache-2.0 */
2+
/**
3+
* @file ml-lxm-service-internal.h
4+
* @date 23 JULY 2025
5+
* @brief Machine Learning LXM(LLM, LVM, etc.) Service API
6+
* @see https://github.com/nnstreamer/api
7+
* @author Hyunil Park <hyunil46.park@samsung.com>
8+
* @bug No known bugs except for NYI items
9+
*/
10+
11+
/**
12+
* @example sample_lxm_service.c
13+
* @brief Sample application demonstrating ML LXM Service API usage
14+
*
15+
* This sample shows how to:
16+
* - Create and configure an LXM session
17+
* - Build prompts with text and instructions
18+
* - Generate streaming responses with custom options
19+
* - Handle token callbacks for real-time processing
20+
*
21+
* Configuration file example (config.json):
22+
* @code
23+
* {
24+
* "single" :
25+
* {
26+
* "framework" : "flare",
27+
* "model" : ["sflare_if_4bit_3b.bin"],
28+
* "adapter" : ["history_lora.bin"],
29+
* "custom" : "tokenizer_path:tokenizer.json,backend:CPU,output_size:1024,model_type:3B,data_type:W4A32",
30+
* "invoke_dynamic" : "true",
31+
* }
32+
* }
33+
* @endcode
34+
*
35+
* Basic usage workflow:
36+
* @code
37+
* // 1. Create session
38+
* ml_lxm_session_h session;
39+
* ml_lxm_session_create("/path/to/config.json", NULL, &session);
40+
*
41+
* // 2. Create prompt
42+
* ml_lxm_prompt_h prompt;
43+
* ml_lxm_prompt_create(&prompt);
44+
* ml_lxm_prompt_append_text(prompt, "Hello AI");
45+
*
46+
* // 3. Set callback using ml_lxm_session_set_event_cb
47+
* ml_lxm_session_set_event_cb(session, token_handler, NULL);
48+
*
49+
* // 4. Generate response with options
50+
* ml_option_h options = NULL;
51+
* ml_option_create(&options);
52+
* ml_option_set(options, "temperature", g_strdup_printf("%f", 1.0), g_free);
53+
* ml_option_set(options, "max_tokens", g_strdup_printf("%zu", (size_t)50), g_free);
54+
* ml_lxm_session_respond(session, prompt, options);
55+
* ml_option_destroy(options);
56+
*
57+
* // 5. Cleanup
58+
* ml_lxm_prompt_destroy(prompt);
59+
* ml_lxm_session_destroy(session);
60+
* @endcode
61+
*
62+
* Complete example with token callback:
63+
* @code
64+
* #include "ml-lxm-service-internal.h"
65+
* #include <iostream>
66+
*
67+
* static void token_handler(ml_service_event_e event,
68+
* ml_information_h event_data,
69+
* void *user_data);
70+
*
71+
* int main() {
72+
* ml_lxm_session_h session = NULL;
73+
* ml_lxm_prompt_h prompt = NULL;
74+
* int ret;
75+
*
76+
* // Check availability first
77+
* ml_lxm_availability_e status;
78+
* ret = ml_lxm_check_availability(&status);
79+
* if (ret != ML_ERROR_NONE || status != ML_LXM_AVAILABILITY_AVAILABLE) {
80+
* std::cout << "LXM service not available" << std::endl;
81+
* return -1;
82+
* }
83+
*
84+
* // 1. Create session with config and instructions
85+
* ret = ml_lxm_session_create("/path/to/config.json", "You are a helpful AI assistant", &session);
86+
* if (ret != ML_ERROR_NONE) {
87+
* std::cout << "Failed to create session" << std::endl;
88+
* return -1;
89+
* }
90+
*
91+
* // 2. Create prompt
92+
* ret = ml_lxm_prompt_create(&prompt);
93+
* if (ret != ML_ERROR_NONE) {
94+
* std::cout << "Failed to create prompt" << std::endl;
95+
* ml_lxm_session_destroy(session);
96+
* return -1;
97+
* }
98+
*
99+
* // Add text to prompt
100+
* ret = ml_lxm_prompt_append_text(prompt, "Explain quantum computing in simple terms");
101+
* if (ret != ML_ERROR_NONE) {
102+
* std::cout << "Failed to append text to prompt" << std::endl;
103+
* ml_lxm_prompt_destroy(prompt);
104+
* ml_lxm_session_destroy(session);
105+
* return -1;
106+
* }
107+
*
108+
* // 3. Set callback using ml_lxm_session_set_event_cb
109+
* ret = ml_lxm_session_set_event_cb(session, token_handler, NULL);
110+
* if (ret != ML_ERROR_NONE) {
111+
* std::cout << "Failed to set callback" << std::endl;
112+
* ml_lxm_prompt_destroy(prompt);
113+
* ml_lxm_session_destroy(session);
114+
* return -1;
115+
* }
116+
*
117+
* // 4. Generate response with custom options
118+
* ml_option_h options = NULL;
119+
* ml_option_create(&options);
120+
* ml_option_set(options, "temperature", g_strdup_printf("%f", 1.2), g_free);
121+
* ml_option_set(options, "max_tokens", g_strdup_printf("%zu", (size_t)128), g_free);
122+
*
123+
* std::cout << "AI Response: ";
124+
* ret = ml_lxm_session_respond(session, prompt, options);
125+
* ml_option_destroy(options);
126+
* if (ret != ML_ERROR_NONE) {
127+
* std::cout << "Failed to generate response" << std::endl;
128+
* }
129+
* std::cout << std::endl;
130+
*
131+
* // 5. Cleanup
132+
* ml_lxm_prompt_destroy(prompt);
133+
* ml_lxm_session_destroy(session);
134+
*
135+
* return 0;
136+
* }
137+
*
138+
* static void token_handler(ml_service_event_e event,
139+
* ml_information_h event_data,
140+
* void *user_data) {
141+
* ml_tensors_data_h data = NULL;
142+
* void *_raw = NULL;
143+
* size_t _size = 0;
144+
* int ret;
145+
*
146+
* switch (event) {
147+
* case ML_SERVICE_EVENT_NEW_DATA:
148+
* if (event_data != NULL) {
149+
* ret = ml_information_get(event_data, "data", &data);
150+
* if (ret == ML_ERROR_NONE) {
151+
* ret = ml_tensors_data_get_tensor_data(data, 0U, &_raw, &_size);
152+
* if (ret == ML_ERROR_NONE && _raw != NULL && _size > 0) {
153+
* std::cout.write(static_cast<const char *>(_raw), _size);
154+
* std::cout.flush();
155+
* }
156+
* }
157+
* }
158+
* break;
159+
* default:
160+
* break;
161+
* }
162+
* }
163+
* @endcode
164+
*/
165+
166+
#ifndef __ML_LXM_SERVICE_INTERNAL_H__
167+
#define __ML_LXM_SERVICE_INTERNAL_H__
168+
169+
#include <stdlib.h>
170+
#include <ml-api-service.h>
171+
#ifdef __cplusplus
172+
extern "C"
173+
{
174+
#endif
175+
176+
/**
177+
* @brief Enumeration for LXM service availability status.
178+
*/
179+
typedef enum
180+
{
181+
ML_LXM_AVAILABILITY_AVAILABLE = 0,
182+
ML_LXM_AVAILABILITY_DEVICE_NOT_ELIGIBLE,
183+
ML_LXM_AVAILABILITY_SERVICE_DISABLED,
184+
ML_LXM_AVAILABILITY_MODEL_NOT_READY,
185+
ML_LXM_AVAILABILITY_UNKNOWN
186+
} ml_lxm_availability_e;
187+
188+
/**
189+
* @brief Checks LXM service availability.
190+
* @param[out] status Current availability status.
191+
* @return ML_ERROR_NONE on success, error code otherwise.
192+
*/
193+
int ml_lxm_check_availability (ml_lxm_availability_e * status);
194+
195+
/**
196+
* @brief A handle for lxm session.
197+
*/
198+
typedef void *ml_lxm_session_h;
199+
200+
/**
201+
* @brief Creates an LXM session.
202+
* @param[in] config_path Path to configuration file.
203+
* @param[in] instructions Initial instructions (optional).
204+
* @param[out] session Session handle.
205+
* @return ML_ERROR_NONE on success.
206+
*/
207+
int ml_lxm_session_create (const char *config_path, const char *instructions, ml_lxm_session_h * session);
208+
209+
/**
210+
* @brief Destroys an LXM session.
211+
* @param[in] session Session handle.
212+
* @return ML_ERROR_NONE on success.
213+
*/
214+
int ml_lxm_session_destroy (ml_lxm_session_h session);
215+
216+
/**
217+
* @brief A handle for lxm prompt.
218+
*/
219+
typedef void *ml_lxm_prompt_h;
220+
221+
/**
222+
* @brief Creates a prompt object.
223+
* @param[out] prompt Prompt handle.
224+
* @return ML_ERROR_NONE on success.
225+
*/
226+
int ml_lxm_prompt_create (ml_lxm_prompt_h * prompt);
227+
228+
/**
229+
* @brief Appends text to a prompt.
230+
* @param[in] prompt Prompt handle.
231+
* @param[in] text Text to append.
232+
* @return ML_ERROR_NONE on success.
233+
*/
234+
int ml_lxm_prompt_append_text (ml_lxm_prompt_h prompt, const char *text);
235+
236+
/**
237+
* @brief Appends an instruction to a prompt.
238+
* @param[in] prompt Prompt handle.
239+
* @param[in] instruction Instruction to append.
240+
* @return ML_ERROR_NONE on success.
241+
*/
242+
int ml_lxm_prompt_append_instruction (ml_lxm_prompt_h prompt, const char *instruction);
243+
244+
/**
245+
* @brief Destroys a prompt object.
246+
* @param[in] prompt Prompt handle.
247+
* @return ML_ERROR_NONE on success.
248+
*/
249+
int ml_lxm_prompt_destroy (ml_lxm_prompt_h prompt);
250+
251+
/**
252+
* @brief Sets runtime instructions for a session.
253+
* @param[in] session Session handle.
254+
* @param[in] instructions New instructions.
255+
* @return ML_ERROR_NONE on success.
256+
*/
257+
int ml_lxm_session_set_instructions (ml_lxm_session_h session, const char *instructions);
258+
259+
/**
260+
* @brief Sets the callback for LXM session events.
261+
* @param[in] session Session handle.
262+
* @param[in] callback Callback function for session events.
263+
* @param[in] user_data User data to be passed to the callback.
264+
* @return ML_ERROR_NONE on success.
265+
* @note This function should be called once per session. Calling it multiple times will return an error.
266+
*/
267+
int ml_lxm_session_set_event_cb (ml_lxm_session_h session, ml_service_event_cb callback, void *user_data);
268+
269+
/**
270+
* @brief Generates an token-streamed response.
271+
* @param[in] session Session handle.
272+
* @param[in] prompt Prompt handle.
273+
* @param[in] options Generation parameters (ml_option_h).
274+
* @return ML_ERROR_NONE on success.
275+
* @note The callback should be set using ml_lxm_session_set_event_cb() before calling this function.
276+
*/
277+
int ml_lxm_session_respond (ml_lxm_session_h session, ml_lxm_prompt_h prompt, ml_option_h options);
278+
279+
#ifdef __cplusplus
280+
}
281+
#endif
282+
#endif
283+
/* __ML_LXM_SERVICE_INTERNAL_H__ */

‎c/src/meson.build‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
nns_capi_common_srcs = files('ml-api-common.c', 'ml-api-inference-internal.c')
22
nns_capi_single_srcs = files('ml-api-inference-single.c')
33
nns_capi_pipeline_srcs = files('ml-api-inference-pipeline.c')
4-
nns_capi_service_srcs = files('ml-api-service.c', 'ml-api-service-extension.c', 'ml-api-service-agent-client.c')
4+
nns_capi_service_srcs = files('ml-api-service.c', 'ml-api-service-extension.c', 'ml-api-service-agent-client.c', 'ml-lxm-service.c')
55

66
if support_nnstreamer_edge
77
nns_capi_service_srcs += files('ml-api-service-query.c')

0 commit comments

Comments
 (0)