ai function helper
1.0.0
A IA Function Helper é um poderoso módulo Node.js que simplifica a integração dos modelos GPT da OpenAI em seus aplicativos. Ele fornece uma maneira estruturada de interagir com os modelos de IA, garantindo respostas consistentes e formatadas.
Instale o auxiliar de função AI usando o NPM:
npm install ai-function-helperAqui está um exemplo simples para você começar:
const { createAiFunctionInstance } = require ( 'ai-function-helper' ) ;
// Create an instance with your OpenAI API key
const aiFunction = createAiFunctionInstance ( 'your_api_key_here' ) ;
// Define your function
const options = {
functionName : 'generate_haiku' ,
model : 'gpt-3.5-turbo' ,
args : { topic : 'spring' } ,
description : 'Generate a haiku about the given topic.' ,
outputSchema : {
type : "object" ,
properties : {
haiku : { type : "string" }
} ,
required : [ "haiku" ]
}
} ;
// Call the function
aiFunction ( options )
. then ( result => console . log ( result . haiku ) )
. catch ( error => console . error ( error ) ) ; Para usar o AI Helper, você primeiro precisa criar uma instância com sua chave de API do OpenAI:
const { createAiFunctionInstance } = require ( 'ai-function-helper' ) ;
const aiFunction = createAiFunctionInstance ( 'your_api_key_here' ) ;Você também pode usar um URL de endpoint personalizado:
const aiFunction = createAiFunctionInstance ( 'your_api_key_here' , 'https://api.openai.com/v1' ) ;Como alternativa, você pode usar uma instância do OpenAI existente:
const OpenAI = require ( 'openai' ) ;
const openai = new OpenAI ( { apiKey : 'your_api_key_here' } ) ;
const aiFunction = createAiFunctionInstance ( openai ) ;Depois de ter uma instância, você pode chamar funções de IA fornecendo opções:
const result = await aiFunction ( {
functionName : 'example_function' ,
model : 'gpt-4o' ,
args : { param1 : 'value1' , param2 : 'value2' } ,
description : 'This is an example function.' ,
outputSchema : {
type : "object" ,
properties : {
result : { type : "string" }
} ,
required : [ "result" ]
}
} ) ; A aiFunction leva um objeto de opções com as seguintes propriedades:
| Opção | Tipo | Descrição | Padrão |
|---|---|---|---|
functionName | corda | Nome da função da IA | 'custom_function' |
args | objeto/string | Argumentos para a função | - |
description | corda | Descrição do propósito da função | - |
outputSchema | objeto | Tipo de retorno esperado (esquema JSON ou esquema Zod) | - |
strictReturn | booleano | Aplicar a validação rigorosa do tipo de retorno | true |
showDebug | booleano | Imprima informações de depuração para console | false |
debugLevel | número | Nível de informação de depuração (0-2) | 0 |
temperature | número | Temperatura de amostragem para o modelo de IA | 0.6 |
frequency_penalty | número | Pena de frequência para o modelo de IA | 0 |
presence_penalty | número | Penalidade de presença para o modelo de IA | 0 |
model | corda | Modelo de IA para usar | 'gpt-4o-mini' |
max_tokens | número | Número máximo de tokens para gerar | 1000 |
top_p | número | Valor P superior para o modelo de IA | null |
blockHijack | booleano | Impedir o seqüestro imediato | false |
blockHijackThrowError | booleano | Lança um erro na tentativa do seqüestro | false |
tools | variedade | Funções auxiliares para usar na função principal | [] |
stream | booleano | Ativar streaming de resposta | false |
streamCallback | função | Retorno de chamada para respostas transmitidas | null |
promptVars | objeto | Variáveis a serem usadas no prompt | {} |
images | String/Array | URL (s) de imagem para modelos de visão | null |
imageQuality | corda | Qualidade da imagem para modelos de visão | 'low' |
minifyJSON | booleano | Minificar a saída JSON | false |
history | variedade | Histórico de conversas para contexto | [] |
forceJsonMode | booleano | Modo JSON Force para modelos não json | false |
timeout | número | Tempo limite para chamadas de API (em milissegundos) | 120000 |
maxRetries | número | Número máximo de tentativas para chamadas de API | 0 |
includeThinking | booleano | Inclua o processo de pensamento da IA na saída de depuração | false |
OUTPUTSCHEMA : define a estrutura esperada da saída da função de IA usando o esquema JSON ou o esquema ZOD. Isso garante que o modelo de IA retorne dados no formato que seu aplicativo espera.
Ferramentas : uma matriz de funções auxiliares que podem ser usadas na função principal da IA. Cada ferramenta é um objeto com name , function_call , description e parameters .
Blockhijack : Quando ativado, esse recurso impede que o modelo de IA siga as instruções nas mensagens do usuário que tentam substituir o comportamento pretendido da função.
PromptVars : permite definir variáveis que serão substituídas na descrição da função, fornecendo mais flexibilidade na engenharia imediata.
Imagens : Ativa o uso de entradas de imagem para modelos capazes de visão, expandindo os tipos de tarefas que a IA pode executar.
Incluindo a identificação : Quando definido como true , esta opção inclui o processo de pensamento da IA na saída de depuração, fornecendo informações sobre como a IA chega às suas conclusões. Isso é particularmente útil para tarefas complexas de solução de problemas e depuração.
A opção includeThinking permite capturar o processo de pensamento da IA antes de gerar a saída final. Este recurso oferece vários benefícios:
Qualidade de resposta aprimorada : ao "pensar" antes de responder, a IA pode organizar seus pensamentos e fornecer respostas mais coerentes e bem estruturadas.
Transparência : você pode ver o raciocínio por trás das respostas da IA, que é útil para depurar e entender como a IA chegou às suas conclusões.
Ajuda de depuração : o processo de pensamento pode ser inestimável ao ajustar os avisos de ajuste ou a solução de problemas inesperados.
Quando ativado, o processo de pensamento da IA é incluído na saída de depuração, mas não é retornado como parte do resultado final. Veja como usá -lo:
const options = {
functionName : 'complex_calculation' ,
args : { expression : '15*87 + ( 129/ (48*0.5) ) +12' } ,
description : 'Perform a complex mathematical calculation and show the steps.' ,
outputSchema : {
type : "object" ,
properties : {
result : { type : "number" }
} ,
required : [ "result" ]
} ,
includeThinking : true ,
showDebug : true // Set this to true to see the thinking process in the console
} ;
const result = await aiFunction ( options ) ; Na saída de depuração, você verá o processo de pensamento anexado em <|start_of_thinking|> e <|end_of_thinking|> tags. Por exemplo:
--- Thinking Process ---
To solve the expression '15*87 + ( 129/ (48*0.5) ) +12', I'll break it down into steps:
1. First, let's solve the parentheses:
(48*0.5) = 24
2. Now we can simplify the division:
129 / 24 = 5.375
3. Let's calculate 15*87:
15*87 = 1305
4. Now we have simplified the expression to:
1305 + 5.375 + 12
5. Let's add these numbers:
1305 + 5.375 = 1310.375
1310.375 + 12 = 1322.375
Therefore, the final result is 1322.375.
--- Parsed JSON Output ---
{
"result": 1322.375
}
Observe que o processo de pensamento é visível apenas na saída de depuração e não afeta a estrutura ou o conteúdo do resultado retornado. Esse recurso é particularmente útil para tarefas complexas, onde entender o raciocínio da IA pode levar a uma melhor engenharia imediata e resultados mais precisos.
Neste exemplo, podemos ver como a IA divide o cálculo complexo em etapas gerenciáveis, facilitando a verificação do resultado e entender a abordagem de solução de problemas. Esse nível de detalhe no processo de pensamento pode ser especialmente valioso para depuração, educação ou quando as etapas para chegar a uma conclusão são tão importantes quanto a resposta final em si.
Ative o streaming para processar respostas em tempo real:
const options = {
// ... other options ...
stream : true ,
streamCallback : ( chunk ) => {
console . log ( 'Received chunk:' , chunk ) ;
}
} ; O recurso de streaming permite processar as respostas de IA em tempo real, o que pode ser particularmente útil para tarefas de longa duração ou quando deseja fornecer feedback imediato aos usuários. Aqui está um exemplo de como usar a opção stream com um streamCallback :
const { createAiFunctionInstance } = require ( 'ai-function-helper' ) ;
const aiFunction = createAiFunctionInstance ( 'your_api_key_here' ) ;
async function generateStory ( ) {
let story = '' ;
const options = {
functionName : 'generate_story' ,
model : 'gpt-4o' ,
args : {
theme : 'space exploration' ,
length : 'short'
} ,
description : 'Generate a short story about space exploration.' ,
// We don't use 'outputSchema' to return a text instead of a JSON
stream : true ,
streamCallback : ( chunk ) => {
const content = chunk . choices [ 0 ] ?. delta ?. content ;
if ( content ) {
story += content ;
console . log ( 'Received chunk:' , content ) ;
// You can update your UI here with the new content
}
}
} ;
try {
const result = await aiFunction ( options ) ;
// The result here will be the complete response
console . log ( 'Final story:' , story ) ;
return story ;
} catch ( error ) {
console . error ( 'Error generating story:' , error ) ;
}
}
generateStory ( ) ;Neste exemplo:
stream: true nas opções para ativar o streaming.streamCallback que recebe pedaços da resposta quando eles chegam.Essa abordagem permite lidar com a resposta da IA em tempo real, que pode ser benéfica para:
Lembre -se de que, ao usar o streaming, o resultado final retornado pela aiFunction será a resposta completa, para que você ainda possa usá -lo, se necessário.
Defina as funções auxiliares a serem usadas na sua principal função de IA:
const options = {
// ... other options ...
tools : [
{
name : "generate_password" ,
function_call : ( { length = 5 , passwordCount = 1 } ) => {
// Password generation logic here
} ,
description : "Generate a random password" ,
parameters : {
type : "object" ,
properties : {
length : { type : "integer" } ,
passwordCount : { type : "integer" }
}
}
}
]
} ;Habilite a proteção contra seqüestros imediatos:
const options = {
// ... other options ...
blockHijack : true ,
blockHijackThrowError : true // Optional: throw error instead of returning a message
} ;Para modelos capazes de visão, você pode incluir entradas de imagem:
const options = {
// ... other options ...
images : 'https://example.com/image.jpg' ,
// Or
images : [ 'https://example.com/image1.jpg' , 'https://example.com/image2.jpg' ] ,
imageQuality : 'high'
} ;Forneça contexto de interações anteriores:
const options = {
// ... other options ...
history : [
{ role : "user" , content : "What's the weather like?" } ,
{ role : "assistant" , content : "I'm sorry, but I don't have access to real-time weather information. Is there anything else I can help you with?" }
]
} ; Aqui estão alguns exemplos envolventes que mostram a versatilidade e o poder do módulo aiFunction :
const options = {
functionName : 'generate_quiz' ,
model : 'gpt-4o' ,
args : { topic : 'space exploration' , difficulty : 'medium' , num_questions : 2 } ,
description : 'Generate a quiz with multiple-choice questions on the given topic.' ,
outputSchema : {
type : "array" ,
items : {
type : "object" ,
properties : {
question : { type : "string" } ,
options : {
type : "array" ,
items : { type : "string" } ,
minItems : 4 ,
maxItems : 4
} ,
correct_answer : { type : "string" }
} ,
required : [ "question" , "options" , "correct_answer" ]
}
}
} ;
const quiz = await aiFunction ( options ) ;
console . log ( JSON . stringify ( quiz , null , 2 ) ) ;Saída esperada:
[
{
"question" : " Which space agency launched the first artificial satellite, Sputnik 1? " ,
"options" : [
" NASA " ,
" Soviet Union " ,
" European Space Agency " ,
" China National Space Administration "
],
"correct_answer" : " Soviet Union "
},
{
"question" : " What year did the Apollo 11 mission successfully land humans on the Moon? " ,
"options" : [
" 1967 " ,
" 1969 " ,
" 1971 " ,
" 1973 "
],
"correct_answer" : " 1969 "
}
] const { z } = require ( 'zod' ) ;
const options = {
functionName : 'create_recipe' ,
model : 'gpt-4o' ,
args : { cuisine : 'Italian' , main_ingredient : 'pasta' , dietary_restriction : 'vegetarian' } ,
description : 'Create a recipe based on the given cuisine, main ingredient, and dietary restriction.' ,
outputSchema : z . object ( {
name : z . string ( ) ,
ingredients : z . array ( z . string ( ) ) ,
instructions : z . array ( z . string ( ) ) ,
prep_time : z . string ( ) ,
cook_time : z . string ( ) ,
servings : z . number ( ) . int ( )
} )
} ;
const recipe = await aiFunction ( options ) ;
console . log ( JSON . stringify ( recipe , null , 2 ) ) ;Saída esperada:
{
"name" : " Vegetarian Pasta Primavera " ,
"ingredients" : [
" 12 oz penne pasta " ,
" 2 cups mixed vegetables (bell peppers, zucchini, carrots) " ,
" 1/4 cup olive oil " ,
" 3 cloves garlic, minced " ,
" 1/2 cup grated Parmesan cheese " ,
" 1/4 cup fresh basil, chopped " ,
" Salt and pepper to taste "
],
"instructions" : [
" Cook pasta according to package instructions. Reserve 1/2 cup pasta water. " ,
" In a large skillet, heat olive oil over medium heat. Add minced garlic and sauté for 1 minute. " ,
" Add mixed vegetables to the skillet and cook for 5-7 minutes until tender-crisp. " ,
" Drain pasta and add it to the skillet with vegetables. Toss to combine. " ,
" Add Parmesan cheese, basil, and pasta water as needed to create a light sauce. " ,
" Season with salt and pepper to taste. Serve hot. "
],
"prep_time" : " 15 minutes " ,
"cook_time" : " 20 minutes " ,
"servings" : 4
} const options = {
functionName : 'analyze_reviews' ,
model : 'gpt-4o' ,
args : {
reviews : [
"The product exceeded my expectations. Great value for money!" ,
"Disappointed with the quality. Wouldn't recommend." ,
"Average product, nothing special but does the job."
]
} ,
description : 'Analyze the sentiment of customer reviews and categorize them.' ,
outputSchema : {
type : "array" ,
items : {
type : "object" ,
properties : {
review : { type : "string" } ,
sentiment : { type : "string" , enum : [ "positive" , "neutral" , "negative" ] } ,
score : { type : "number" , minimum : 0 , maximum : 1 }
} ,
required : [ "review" , "sentiment" , "score" ]
}
}
} ;
const sentiment_analysis = await aiFunction ( options ) ;
console . log ( JSON . stringify ( sentiment_analysis , null , 2 ) ) ;Saída esperada:
[
{
"review" : " The product exceeded my expectations. Great value for money! " ,
"sentiment" : " positive " ,
"score" : 0.9
},
{
"review" : " Disappointed with the quality. Wouldn't recommend. " ,
"sentiment" : " negative " ,
"score" : 0.2
},
{
"review" : " Average product, nothing special but does the job. " ,
"sentiment" : " neutral " ,
"score" : 0.5
}
] const { z } = require ( 'zod' ) ;
const options = {
functionName : 'create_travel_itinerary' ,
model : 'gpt-4o' ,
args : { destination : 'Tokyo' , duration : 3 , interests : [ 'technology' , 'culture' , 'food' ] } ,
description : 'Create a daily travel itinerary for the specified destination and duration, considering the traveler's interests.' ,
outputSchema : z . object ( {
destination : z . string ( ) ,
duration : z . number ( ) . int ( ) ,
daily_plans : z . array ( z . object ( {
day : z . number ( ) . int ( ) ,
activities : z . array ( z . object ( {
time : z . string ( ) ,
activity : z . string ( ) ,
description : z . string ( )
} ) )
} ) )
} )
} ;
const itinerary = await aiFunction ( options ) ;
console . log ( JSON . stringify ( itinerary , null , 2 ) ) ;Saída esperada:
{
"destination" : " Tokyo " ,
"duration" : 3 ,
"daily_plans" : [
{
"day" : 1 ,
"activities" : [
{
"time" : " 09:00 " ,
"activity" : " Visit Akihabara " ,
"description" : " Explore the technology and electronics district, known for its gadgets and anime culture. "
},
{
"time" : " 13:00 " ,
"activity" : " Lunch at a Robot Restaurant " ,
"description" : " Experience a unique dining experience with robot performances. "
},
{
"time" : " 15:00 " ,
"activity" : " Tour the Miraikan Science Museum " ,
"description" : " Discover cutting-edge technology and scientific innovations at this interactive museum. "
}
]
},
{
"day" : 2 ,
"activities" : [
{
"time" : " 10:00 " ,
"activity" : " Visit Senso-ji Temple " ,
"description" : " Explore Tokyo's oldest Buddhist temple and experience traditional Japanese culture. "
},
{
"time" : " 14:00 " ,
"activity" : " Tea Ceremony in Hamarikyu Gardens " ,
"description" : " Participate in a traditional Japanese tea ceremony in a beautiful garden setting. "
},
{
"time" : " 18:00 " ,
"activity" : " Dinner at Tsukiji Outer Market " ,
"description" : " Enjoy fresh sushi and local delicacies at the world-famous fish market area. "
}
]
},
{
"day" : 3 ,
"activities" : [
{
"time" : " 09:00 " ,
"activity" : " Visit teamLab Borderless " ,
"description" : " Immerse yourself in a digital art museum that blends technology and creativity. "
},
{
"time" : " 13:00 " ,
"activity" : " Ramen Tour in Shinjuku " ,
"description" : " Sample various styles of ramen at some of Tokyo's best ramen shops. "
},
{
"time" : " 16:00 " ,
"activity" : " Shopping in Ginza " ,
"description" : " Explore high-end technology stores and experience Japanese retail innovation. "
}
]
}
]
} const options = {
functionName : 'analyze_stock' ,
model : 'gpt-4o' ,
args : { symbol : 'AAPL' , timeframe : '1 year' } ,
description : 'Analyze the stock performance and provide insights based on the given symbol and timeframe.' ,
outputSchema : {
type : "object" ,
properties : {
symbol : { type : "string" } ,
currentPrice : { type : "number" } ,
yearlyPerformance : { type : "number" } ,
technicalIndicators : {
type : "object" ,
properties : {
RSI : { type : "number" } ,
MACD : {
type : "object" ,
properties : {
value : { type : "number" } ,
signal : { type : "number" } ,
histogram : { type : "number" }
} ,
required : [ "value" , "signal" , "histogram" ]
}
} ,
required : [ "RSI" , "MACD" ]
} ,
recommendation : { type : "string" , enum : [ "Buy" , "Hold" , "Sell" ] }
} ,
required : [ "symbol" , "currentPrice" , "yearlyPerformance" , "technicalIndicators" , "recommendation" ]
}
} ;
const stockAnalysis = await aiFunction ( options ) ;
console . log ( JSON . stringify ( stockAnalysis , null , 2 ) ) ;Saída esperada:
{
"symbol" : " AAPL " ,
"currentPrice" : 178.25 ,
"yearlyPerformance" : 0.35 ,
"technicalIndicators" : {
"RSI" : 62.5 ,
"MACD" : {
"value" : 2.1 ,
"signal" : 1.8 ,
"histogram" : 0.3
}
},
"recommendation" : " Buy "
} Esses exemplos demonstram como usar o auxiliar de função da IA para várias tarefas, da geração de conteúdo à análise de dados. Cada exemplo inclui um esquema outputSchema detalhado (alternando entre o esquema JSON e os formatos ZOD), garantindo a saída estruturada e validada do modelo AI.
Use nomes de funções específicos : escolha nomes de funções claros e descritivos para ajudar a IA a entender o contexto.
Forneça descrições detalhadas : quanto mais contexto você fornece na descrição, melhor a IA pode entender e executar a tarefa.
Defina esquemas de retorno precisos : use esquemas detalhados outputSchema para garantir que você obtenha a estrutura de dados exata necessária.
Utilize ferramentas para tarefas complexas : para tarefas que requerem cálculos específicos ou dados externos, defina ferramentas personalizadas para lidar com esses aspectos.
Lidar com os erros graciosamente : use blocos de try-capath e considere definir o tempo limite apropriado e os valores de repetição para o tratamento de erros robustos.
Otimize para uso do token : esteja atento à duração de seus avisos e considere usar minifyJSON para obter grandes saídas para reduzir o consumo de token.
Use streaming para respostas longas : para tarefas que podem gerar respostas longas, considere usar a opção de streaming para processar a resposta em tempo real.
Aproveite o histórico de conversas : para interações múltiplas, use a opção de history para fornecer contexto de trocas anteriores.
P: Posso usar este módulo com outros provedores de IA? R: Atualmente, o AI Function Helper foi projetado para trabalhar com os modelos do OpenAI. O suporte a outros provedores pode ser adicionado em versões futuras.
P: Como posso depurar se não estou obtendo a saída esperada? R: Habilite a depuração definindo showDebug: true e ajustando o debugLevel . Isso fornecerá mais informações sobre as chamadas e respostas da API.
P: Este módulo é adequado para o uso da produção? R: Sim, mas sempre verifique se você possui o manuseio adequado de erros e os limites de taxa de respeito definidos pelo OpenAI.
P: Posso usar isso para transmitir grandes quantidades de dados? R: Sim, você pode usar a opção stream para lidar com grandes respostas com eficiência.
P: Como o módulo lida com as teclas da API com segurança? R: O módulo não lida com o armazenamento ou segurança da chave da API. É sua responsabilidade gerenciar e fornecer a chave da API com segurança ao criar uma instância.
Realizamos testes extensos em vários modelos de IA para avaliar sua capacidade de gerar saídas JSON de complexidade variável enquanto aderimos a formatos especificados. Esses testes ajudam a demonstrar a versatilidade e a confiabilidade do módulo auxiliar de função da IA em diferentes modelos de IA.
Para garantir testes abrangentes em uma ampla gama de modelos de IA, incluindo aqueles que não são fornecidos diretamente pelo OpenAI, utilizamos o Litellm como proxy. A Litellm é uma ferramenta poderosa que fornece uma interface unificada para vários provedores de IA e modelos locais (via Ollama), oferecendo um URL do ponto de extremidade compatível com o OpenAI. Essa abordagem nos permitiu integrar e testar perfeitamente vários modelos de IA com nosso ajudante de função de IA, demonstrando sua flexibilidade e ampla compatibilidade.
| Modelo | Taxa de sucesso | Duração média |
|---|---|---|
| Fireworks/LLAMA-V3P1-405B-INSTRUTA | 100,00% | 16887.67ms |
| Groq/llama-3.1-70b-versatile | 100,00% | 2154.89ms |
| Claude-3-Haiku-20240307 | 100,00% | 3175.72ms |
| GPT-3.5-Turbo | 88,89% | 3398.67ms |
| GPT-4O-MINI | 100,00% | 5699.72ms |
| GPT-4O | 100,00% | 5673.00ms |
| CLAUDE-3-5-SONNET-20240620 | 100,00% | 5940,50ms |
| Gemini-1.5-Flash | 88,89% | 5150,00ms |
| Gemini-1.5-Pro | 100,00% | 10066.06ms |
| Gemma2: 9b (Ollama) | 100,00% | 13368.94ms |
Os testes cobrem uma ampla gama de funcionalidades, de cálculos simples a geração e análise de dados complexas. Algumas das categorias de teste incluem:
Para obter resultados detalhados de cada caso de teste e desempenho do modelo, consulte os seguintes arquivos:
Se você deseja executar os testes ou contribuir para melhorá -los, pode encontrar o script de teste em nosso repositório do GitHub:
Esses testes demonstram a capacidade do auxiliar de função da IA de trabalhar com vários modelos de IA e lidar com uma ampla gama de complexidades de tarefas. Eles também mostram a capacidade do módulo de aplicar saídas estruturadas, facilitando a integração do conteúdo gerado pela IA em seus aplicativos.
Alguns testes são "estupidamente" complexos e são projetados para empurrar os limites dos modelos de IA. Esses testes não devem ser práticos, mas para demonstrar a capacidade do ajudante da função da IA de lidar com cenários desafiadores. A maioria dos testes com falha pode ser concluída com sucesso, dando ao modelo de IA mais contexto ou refinando os avisos de entrada.
Ao alavancar o Litellm, expandimos a compatibilidade de nosso auxiliar de função de IA além dos modelos Openai, permitindo que os usuários trabalhem com uma variedade diversificada de provedores de IA e modelos locais, mantendo uma interface consistente. Essa abordagem não apenas amplia a aplicabilidade de nossa ferramenta, mas também fornece aos usuários maior flexibilidade na escolha dos modelos de IA que melhor atendem às suas necessidades e restrições específicas.
As contribuições são bem -vindas! Se você quiser contribuir, bifurque o repositório e use uma filial de recursos. Os pedidos de tração são calorosamente bem -vindos.
A IA Function Helper é um software de código aberto licenciado sob a licença do MIT.
